PUT/GET request processing occurs when an application thread issues the IEFSSREQ macro to initiate data set selection. The input SSOB and SSS2 control blocks, provided by the application thread, specifies the selection criteria used to select a data set. The application thread can use a wide variety of selection criteria to select a SYSOUT data set to be processed.

Once the application thread receives a data set from the JES, you must allocate (through a dynamic allocation with the data set name that is returned from SSS2DSN) the data set to process it. During this allocation, dynamic allocation requires DALBRTKN text unit. JES performs the initialization of this text unit. The application thread must move the address from field SSS2BTOK into a text unit pointer field for the JES-provided DALBRTKN text unit. The actual processing of the SYSOUT data set depends upon your specific application. After your application thread has completed processing of the data set, it then unallocates the data set with the text unit of DUNDDNAM specifying the DDNAME of the returned data set from the original allocation. The allocation/unallocation of the data set must occur once per returned data set.

The PUT processing occurs when the application thread subsequently issues a following IEFSSREQ macro to select another data set. You can use fields in the optional disposition section of the SSS2 to change certain attributes of the previously obtained data set from the prior IEFSSREQ call.

A difference between SAPI and Process SYSOUT (SSI Function Code 1) during unallocation is that SAPI does not process any of the unallocation text units as occurs in Process SYSOUT. The SSS2 provides specific disposition fields for JES to use during the subsequent SAPI PUT/GET call to provide for disposition processing. From a JES processing point of view, the disposition processing for the previous data set occurs prior to the processing of the selection of the next data set, but both are occurring within the same IEFSSREQ call by the application thread.

You must provide at least SAF UPDATE authority for the JESSPOOL resource class to the application thread to issue the SAPI PUT/GET call correctly.

If the application does not provide for multi-tasking, it must follow the protocol below. If the application does provide for multi-tasking, each application thread in the address space must follow the protocol shown in Figure 1.

Figure 1. Protocol for the SAPI PUT/GET Call

Programming Considerations for PUT/GET

• The application thread must provide a pointer to an ECB in field SSS2ECBP if the application thread wants JES to post it when newly created work has characteristics matching the thread's selection criteria. This occurs after JES returns SSS2EODS for a PUT/GET request. If an ECB is not supplied, it is the responsibility of the thread to initiate an IEFSSREQ request.
• For JES3 only, once the application thread begins PUT/GET processing, a COUNT or BULK MODIFY request can not be initiated prior to receiving an SSS2EODS response to a PUT/GET request.
• SSS2CDS contains a 1 for the single returned data set in a SAPI GET/PUT call. If the data set disposition is DELETE, all copies of the data set are deleted.
• Information contained within the SYSOUT data set's scheduler work blocks (SWBs) can also be returned to the application thread. Much of the information contained within the SWB is normally not processed by JES, and therefore much more information about the data set can be retrieved from the SWB than is returned in fields of the SSS2. Examples of such information contained within the SWB are NAME, BUILDING, ADDRESS, and so on.

  The application thread needing to retrieve this SWB information, sets either SSS2FSWB or SSS2FSWT in flag byte SSS2MSC1 when issuing a PUT/GET request. The setting of SSS2FSWB implies SSS2FSWT processing as well. JES then provides the application thread the information that can be used when the application thread invokes the SJF services to retrieve this SWB information. These services are either SJFREQ REQUEST=RETRIEVE or SWBTUREQ REQUEST=RETRIEVE.

  Note that the use of either settings cause JES to perform additional processing overhead to satisfy this request. Thus, the application thread should not request the SWB information unless needed by the application. Examples of this additional overhead are spool I/O to read the stored SWBTU blocks, SJF services that JES needs to invoke to prepare the environment, additional GETMAINs needed to satisfy the request.

  If the application thread sets either SSS2FSWT or SSS2FSWB, JES returns in output field SSS2SWTU a single SWBTU that can be used as input to a subsequent SWBTUREQ REQUEST=RETRIEVE call made by the application thread. Mapping macro IEFSJTRP is used when issuing this SWBTUREQ request. Field SJTRSTUP can be set with the contents of SSS2SWTU when issuing this request. Set field SJTRSWBN with a binary 1 to indicate a single SWBTU block is being used for the SWBTUREQ call. The application thread does not need to explicitly provide storage for the SWBTU block or free it; that is JES's responsibility.

  If the application thread sets SSS2FSWB, JES returns in output field SSS2SWBT an output descriptor token that can be used as input to a subsequent SJFREQ REQUEST=RETRIEVE call made by the application thread. This is in addition to the SSS2FSWT processing previously described. Mapping macro IEFSJREP is used when issuing this SJFREQ request. Field SJRETOKN can be set with the contents of SSS2SWBT when issuing this request. The application thread does not need to explicitly provide storage for the output descriptor token, or free it; that is JES's responsibility.

  In the SSS2, reason code field SSS2WRTN contains either a value of SSS2WOK (0) or SSS2WERR (4). SSS2WOK indicates that JES processing needed for SWB retrieval was completely successful, and output fields SSS2SWBT and SSS2SWTU can be used as described above. If SSS2WRTN is set with SSS2WERR, then an error occured indicating neither SSS2SWTU or SSS2SWBT fields can be used. If this is the case, reason code field SSS2WRSN is set with an indicator of the type of error that prevented JES from providing the SWB information.

  Note that this information provided is primarily to be used as diagnostic information, because the application thread can not affect the JES processing directly that led to the error. Accordingly, receiving such a SWB processing error does not affect the rest of JES processing. The data set is still able to be processed by the application thread; only the ability to issue either the SWBTUREQ or SJFREQ macro services by the application thread is affected and must not be attempted.

  See z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO for additional information concerning the use of the SJFREQ and SWBTUREQ services to retrieve the information in the SWB by either, or both, of the methods described.

• It is the responsibility of the application thread to understand the implications of disposing a data set as KEEP. Because of the potential to process the data set again, the application thread must ensure a loop condition does not arise.
• An EOD (SSOBRETN=SSS2EODS) response is a possible return only for PUT/GET processing. When SAPI returns SSS2EODS to the application thread, the application thread can do one of the following:
  • Wait on its supplied ECB for a post from JES. This post indicates SYSOUT has just been generated that contains characteristics matching the application thread's selection criteria.

    The application can then issue another IEFSSREQ to obtain this data set from the JES. Since multiple applications can be posted from the single piece of work appearing on the queue, there is no guarantee that once posted, a thread will not receive an immediate SSS2EODS return again (that is, another thread received the work).

  • Issue another IEFSSREQ request after changing its selection criteria.
  • Issue another IEFSSREQ request with the SSS2CTRL flag set indicating the application thread is terminating.
  • Issue a COUNT request.
  • Issue a BULK MODIFY request.
• The application must provide DALSSREQ (supplying the JES subsystem name (for example, JES2 or JESA or JES3)) and a dynamic allocation text unit pointer that contains the address supplied in SSS2BTOK. In addition, your application thread must supply a text unit with DALDSNAM that uses the data set name returned in SSS2DSN.
  Note: In JES3 you can override the default number of buffers to be used when reading from the data set by specifying the text unit for BUFNO. The default is 2 spool tracks of buffers. Specifying 0 or 1 will cause the default to be used.

  The subsequent dynamic allocation call is depicted in Figure 2.

Figure 2. Control Blocks of DYNALLOC Call for SAPI-Provided Data Set