Output Parameters

Output parameters for the function routine are:

SSOBRETN
SSSO

SSOBRETN Contents: When control returns to your external writer and register 15 contains a zero, the SSOBRETN field contains one of the following decimal values:

Value (Decimal)

Meaning

SSSORTOK (0)

Successful completion.

SSSOEODS (4)

There are no more data sets to select with the requested selection criteria.

Your external writer has the following options:

Wait until new work becomes available.
See The Writer Communication Area for information about the ECB that will be posted when work is available. In JES2, this POST only occurs for those external writers that are running as started tasks, and not batch jobs.
Modify the criteria for new work.
Your external writer may modify some of the entry criteria (for example, change the form number) to indicate a new selection, and initiate the IEFSSREQ process. Do not issue an IEFSSREQ with the SSSOCTRL bit set when the work is for a different set of characteristics.
Perform job-level (update) disposition (JES3 only).
For example, your function may have been leaving data sets on the spool until all the data sets from the job have been completely and successfully processed. Now, the external writer can perform a job-level disposition of delete with a subsequent IEFSSREQ call specifying the job ID.
End current activity.
Issue a final IEFSSREQ with the SSSOCTRL bit set. This completely disassociates the external writer from the JES. Perform this final call only when your external writer is ready to end the operation.

SSSONJOB (8)

Job not found.

You specified the job name as a selection criterion, but the job name specified in the SSSOJOBN field did not match any job in the system.

SSSOINVA (12)

Invalid search argument.

The job ID specified in the SSSOJOBI field failed syntactical parsing, or both the SSSOWTRN bit and the SSSOUSER bit had also been set in the SSSOFLGA flag byte.

SSSODUPJ (20)

Duplicate job names

During a retrieval request, more than one job was found matching the name in the SSSOJOBN field. A job ID should be specified as a selection criteria to uniquely identify the job.

SSSOINVJ (24)

Invalid job name/job ID combination

During a retrieval request, a job name and job ID were specified as selection criteria, but the job name is not associated with the job ID that the external writer supplied.

SSSOIDST (28)

Invalid destination specified in field SSSODEST.

The return code information depends on which JES is being used:

JES2: The supplied destination did not exist in the JES destination routing tables.

JES3: The supplied destination is not syntactically correct (See z/OS MVS JCL Reference for the correct syntax) or a valid NJE destination was supplied (an external writer cannot select work destined for NJE nodes).

SSSOAUTH (32)

Authorization failed

(JES3 only) The user exit IATUX30 denied the external writer access to this request.

SSSOTKNM (36)

Token map failed

The requested RACROUTE TOKENMAP function failed. JES does not set the SSSOTKNG bit, and no token is provided in the field pointed to by the SSSOSECT field.

SSSO Contents: The SSSO control block contains the following information about the data set returned from your external writer's retrieval request:

Field Name

Description

SSSOFLG2

Flag byte

SSSODDST — DD name set in the extension.
JES sets this flag upon return from a retrieval request, so that your external writer knows that the SSSOPRCD, SSSOSTPD, and SSSODDND fields have been returned with the three part DDNAME of proc-step name, step name, DDNAME.

SSSOCOPY

Number of copies.

JES provides the data set to your external writer as many times as the copy count from the creating JCL specifies it.

The value of this field depends on which JES is being used:

JES2: This field is always set to '1' on a retrieval request.

JES3: This field is always set to '1' on a retrieval request.

SSSOJOBN

Job name associated with the returned data set (retrieval request).

SSSOJOBI

Job ID associated with the returned data set (retrieval request).

SSSOCLAS

Class associated with the returned data set (retrieval request).

If your external writer set the SSSOSCLS bit and the SSSOCLSL field, this class matches a class in the list contained in the SSSOCLSL field (if a multiple class list was specified), or the single class in the SSSOCLSL field (if only one class was specified).

SSSOMLRL

Maximum logical record length associated with the returned data set.

For JES3, if the length in the SYSOUT data set was not valid, a zero is returned. If the data set is a system data set, such as JESJCL, then a value of '133' is returned.

SSSODEST

Destination associated with the returned data set (retrieval request).

SSSOPGMN

Writer name or user ID associated with the returned data set (retrieval request, if available).

The specific information returned depends on the setting of the SSSOWTRN or SSSOUSER bits (retrieval request).

JES2: If neither the SSSOWTRN or SSSOUSER bits are specified, then this field contains the writer name associated with this data set.

Note: The SSSOPGMN field is filled in regardless of whether the SSSOSPGM bit is set. It contains a user ID only when the SSSOUSER bit is set.

SSSODSN

Returned data set name (retrieval request).

Upon return from a retrieval request, your external writer must use this name in the dynamic allocation of the data set. See Processing Flow for Single Data Set Requests for additional details.

The returned data set name is in the fully-qualified, form of: userid.jobname.jobid.dsidentifier.dsname (JES2) or userid.jobname.jobid.dsnumber.dsname (JES3).

SSSOFORM

First four characters of the form name associated with the returned data set name (retrieval request). The SSSOFOR8 field contains the 8-character form name.

SSSOWTRC

Pointer to a communication area for your external writer for a retrieval request.

This area contains additional information about the:

Data set
Owning job
Wait-for-work ECB.

Your external writer might need to use this information in its processing. See The Writer Communication Area for more information.

The fields that follow from the SSSOFLG5 field through the SSSOOGNM field are available as output fields only when you specify SOEXT=YES on the IEFSSSO invocation. The external writer sets the SSSOPSEE bit. IBM® recommends that you specify SOEXT=YES on the IEFSSSO invocation, as additional information is returned to the external writer.

Field Name

Description

SSSOFLG5

Flag byte

SSSOTKNG — Token mapped.
JES sets the SSSOTKNG bit if the token was returned to the version requested by your external writer through the setting of the SSSOTKNR on the retrieval request.

SSSOSECT points to the returned token with its new version and length.
SSSOGNVA — (JES2 only) Output group name provided in the SSSOOGNM field for a retrieval request.

SSSOLNCT

Line count of the returned data set provided for a retrieval request.

The value is correct if the task that created the SYSOUT data set went through end-of-task processing.

The line count includes only records with a non-zero text length that have data associated with them. The count does not include records that start with machine immediate control characters. For example, if a 600-line data set is produced with machine carriage control characters and includes one Skip-to-Channel-1-Immediate command every 60 lines, then there would be 610 records in the data set, but field SSSOLNCT would have a value of 600.

SSSOPRCD

Proc step name of the returned data set provided if:

JES set the SSSODDST bit upon return to your external writer.
A retrieval request is being made.

SSSOSTPD

Data set step name of the returned data set provided if:

JES set the SSSODDST bit upon return to your external writer.
A retrieval request is being made.

SSSODDND

Data set ddname of the returned data set provided if:

JES set the SSSODDST bit upon return to your external writer.
A retrieval request is being made.

SSSOSECT

Pointer whose contents remain unchanged from the retrieval request, but whose address now points to the returned data set's SAF token.

If your external writer did not set the SSSOTKNR bit, JES copied the token to the address specified in the SSSOSECT field. This copy was performed assuming that the receiving length is as long as the length of a version 1 security token. If your external writer did not allocate enough storage at the address pointed to by the SSSOSECT field, a protection exception might occur.

If both:

Your external writer set the SSSOTKNR bit to indicate to SAF to return a token with a different version and length on the retrieval request, and JES successfully performed this function.
JES set the SSSOTKNG bit

The SSSOSECT field points to the token in the correct format.

SSSOFOR8

Form name of the returned data set name for a retrieval request.

SSSOACCT

(JES2 only) Address of an accounting string for the returned data set for a retrieval request, or zero.

Your external writer must be in AMODE 31 to access this data. The data is in the following format:

A 1-byte field containing the number of pairs that follow.
Zero or more accounting pairs, each of the form:
- A 1-byte field containing the length of the accounting string.
- The actual accounting string itself with the length that is specified in the first byte.
  A length of zero indicates an omitted field.

For example, if the original accounting information had been specified as (12,,ABCD), the field pointed to by the SSSOACCT would be: '03 02 F1 F2 00 04 C1 C2 C3 C4' in storage.

SSSOOGNM

(JES2 only) JES2 output group name of the returned data set.

The SSSOGNVA flag is set if the field is valid.