Implementing User Programs › Write a SUBSYS Program › Subsystem Program Considerations

Subsystem Program Considerations

When writing a subsystem program, the following should be considered:

• Use the new format parameter list. Remember that you can validate the format by checking that the value pointed to by R1 on entry is equal to R1.

  C     R1,0(,R1)
  

  BE    NEWFMT
  B     OLDFMT
  

  The following facilities are only available if the new parameter list format is used:

  • An NCL process cleanup call
  • System initialization calls
  • System shutdown calls
  • Private correlator calls
  • Callback API
• Check whether your program has been called as a subsystem rather than an &CALL attach. If an asterisk is found in the subsystem name field in the (new) parameter list, then it is an &CALL attach, not a SUBSYS call.
• A subsystem gets a private correlator word for each unique NCL process that calls it. This correlator word can be altered (it starts as 0) and is remembered and returned on the next call for that NCL process. It is an ideal place to anchor process-related control blocks. The shared correlator is shared with all subsystems or other &CALLed programs for this NCL process.
• Any NCL process that calls a subsystem using the new parameter list causes a cleanup call to be provided to that subsystem. This call is made regardless of the type of NCL process termination (normal, abnormal, and so on). The private correlator is provided, and this allows the subsystem to clean up any control blocks as required. If an NCL process is flushed while on a SUBSYS call, the subsystem is not notified of the fact until later. It need not worry about the process disappearing while actually processing the current call.
• A SUBSYS DEFINE (without NOSTART) or SUBSYS START command sends an initialization call to the subsystem. This allows the subsystem to initialize its environment. It should anchor any control blocks in the SUBSYS correlator in the new format parameter list.
• A SUBSYS STOP sends a termination call to the subsystem program. This allows the subsystem to clean up any control blocks, and so on, prior to being detached.
• If your product is shut down, a system shutdown call is sent to the subsystem. It must quickly clean up its environment. It is force-detached several seconds later regardless of whether it is finished or not.
• Only as many parameters as were passed can be returned to a caller. This is the same as the previous &CALL. Each parameter is limited to 256 characters of data. Binary values are preserved both on input and on return. Be sure to set the lengths correctly.
• All calls to a specific subsystem are queued and processed in turn. This means that, if the subsystem code takes a long time to process a call (for example, issuing a WAIT on VTAM input), all pending calls are also delayed. This is a restriction of the current implementation.
• This can be avoided by queuing requests to the subsystem to a manager process (using the INTQ command and a globally known NCLID). This manager process talks to the subsystem on behalf of all users of the subsystem. Then the subsystem code can wait on many events and return the first event to the manager, which can then pass it back to the requestor.
• If the subsystem ABENDs, the subsystem will stop. It can be restarted.
• SUBSYS FORCE is useful when a subsystem hangs.
• The subsystem load module must reside in a library accessible to your product region. Typically this is the STEPLIB. Remember that your product libraries must be authorized. This means that any libraries in this STEPLIB concatenation must also be authorized. This is a security consideration.
• 31-bit mode programs are supported. All supplied control blocks (for example PARMLIST) are always below the 16mb line.
• If performing multiple functions, use the first parameter passed, as a function indicator:

  &CALL SUBSYS=SUB1 OPEN ....       
  &CALL SUBSYS=SUB1 READ ....       
  &CALL SUBSYS=SUB1 READ ....       
  &CALL SUBSYS=SUB1 CLOSE ...