SJFREQ RETRIEVE service

SJFREQ RETRIEVE service

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
SA23-1375-00

The SJFREQ RETRIEVE service retrieves keyword subparameter information in text unit format from output descriptors. These output descriptors can be specified either on an OUTPUT JCL statement or through dynamic output. Your application can invoke this service to retrieve output descriptor information in a functional subsystem environment.

Programming requirements

An application must complete the following steps to issue a RETRIEVE request:

Obtain storage for the RETRIEVE parameter list (IEFSJREP) and initialize the fields. Place the address of IEFSJREP in the PARM parameter.
Provide a keyword list (SJRELIST). The keyword list contains the keywords for which the application wants information retrieved. SJFREQ RETRIEVE keyword list describes the list.
Issue SJFREQ RETRIEVE.

SJFREQ RETRIEVE keyword list

The keyword list contains paired fields; each pair consists of a keyword field and a pointer field. In the list, the application specifies the JCL keywords for which information is to be retrieved. For each keyword specified, the RETRIEVE service returns in SJRETPAD a pointer to the text unit pointer list associated with the keyword.

The following table shows the SJRELIST paired fields and their offsets and lengths. The fields that the application initializes are indicated.

Field Name	Offset (bytes)	Value Length (bytes)	Value to be assigned
SJRELIST
SJREKEYW	0 (X'0')	8	keyword 1 (initialized by application)
SJRETPAD	8 (X'8')	4	pointer (returned by the system)
SJREKEYW	12 (X'C')	8	keyword 2 (initialized by application)
SJRETPAD	20 (X'14')	4	pointer (returned by the system)
.	.	.	.
.	.	.	.

In addition to JCL keywords, SJFREQ can also return a text unit for the keyword providing special TCP/IP support. This text unit has the following characteristics in the Output Descriptor.

Characteristic:
Keyword Parameter:	IPADDR
Key in Hex:	8005
Maximum number of Value
Fields:	1
Length of Value Field:	0 - 124
Value Field:	EBCDIC text '40'X - 'FE'X
Function:	IP address extracted from the DEST='IP:ip-address' format of the DEST=keyword

SJFREQ RETRIEVE input parameters

In addition to providing a keyword list, for each SJFREQ invocation, you need to initialize certain fields of parameter list IEFSJREP. The list of parameters and descriptions of their values are below.

SJREID

The identifier ‘SJRE’ of the RETRIEVE parameter list. Assign the symbolic equate SJRECID to this field.

SJREVERS

The current version number of the RETRIEVE parameter list. Assign the symbolic equate SJRECVER to this field.

SJREFLAG

The environment control flag.

SJRENOCU: Indicates whether the SJF environment is preserved from call to call or obtained for each call. Set to one to preserve the environment from call to call. Set to zero to obtain a new environment for a call.

SJRELEN

The length of the RETRIEVE parameter list (IEFSJREP). Assign the symbolic equate SJRELGTH to this field.

SJRESTOR

The local working storage pointer or zero. This field must contain zero on the first RETRIEVE call. On subsequent calls, the field contains the value returned from the most recent RETRIEVE call. Use the returned value for subsequent calls.

SJREJDVT

Enter zero for this field on input. This field must contain zero on the first RETRIEVE call. On subsequent calls, the field contains the value returned from the most recent RETRIEVE call. Use the returned value for subsequent calls.

SJRETOKN

Enter the output descriptor token in this field. If you are coding a Print Service Facility (PSF) exit, refer to PSF/MVS System Programming Guide for information on obtaining the output descriptor token. The token can be obtained from the GDSOUTK field in data area IAZFSIP.

SJREAREA

The address of the storage area in which RETRIEVE is to return the keyword subparameter information in text unit format from output descriptors.

SJRESIZE

The amount of the storage allocated for the output descriptor information.

SJRENKWD

The number of keywords passed in the keyword list (SJRELIST).

SJREKWDL

The address of the keyword list (SJRELIST).

SJFREQ RETRIEVE output parameters

In addition to the output provided in the keyword list, the RETRIEVE service returns data in several fields of the IEFSJREP parameter list. The list of output parameters and their descriptions are below.

SJREREAS: Contains a reason code returned from the RETRIEVE service. This field contains a value when register 15 contains a return code other than zero.
SJREKERR: Contains the address of the first keyword in the keyword list that caused the error.
SJRETPAD: Contains the address of the list of text unit pointers. Each text unit pointer points to a returned text unit. The last text unit has the high-order bit set to one.

ABEND codes

None.

SJFREQ RETRIEVE return and reason codes

SJFREQ RETRIEVE return codes appear in register 15. When SJFREQ returns control to your program, SJREREAS contains a reason code when register 15 contains a nonzero value. Return and reason codes are defined in macro IEFSJRC. The following table identifies the hexadecimal return and reason code combinations, tells what each means, and recommends an action you should take.

Table 1. Return and Reason Codes for the SJFREQ RETRIEVE Service
Return Code	Reason Code	Meaning and Action
0	000	Meaning: RETRIEVE processing completed successfully. Action: None.
4	002	Meaning: Program error. The token specified in SJRETOKN is not valid. Action: Specify a valid token in SJRETOKN.
4	004	Meaning: Program error. The RETRIEVE request was not processed. The value specified in SJREJDVT is not valid. Action: Set SJREJDVT to hexadecimal zeros or to the value returned on the previous call.
4	005	Meaning: System error. The information referenced by parameter field SJREJDVT does not exist. Action: SJF did not initialize properly. Contact the appropriate IBM® support personnel.
4	0C8	Meaning: Program error. SJRETOKN refers to a JCL statement that is not valid. Action: Supply a value in SJRETOKN that refers to a valid JCL statement.
4	0C9	Meaning: Program error. A keyword in the keyword list is not defined to the JCL statement referred to by SJRETOKN. Action: SJREKERR contains the address of the keyword in error. Correct or delete the keyword in error.
4	258	Meaning: Program error. The area specified by SJRESIZE is less than the minimum allowed. Action: Define SJRESIZE to a size that can contain at least one text unit.
4	25B	Meaning: Program error. No storage area address was specified. Action: Specify a storage area address in SJREAREA.
4	25C	Meaning: Program error. The value in SJRENKWD indicates that no keywords were specified. Action: Specify a value of one or greater for SJRENKWD.
4	25D	Meaning: Program error. No keyword list address was specified. Action: Specify a keyword list address in SJREKWDL.
4	25F	Meaning: Program error. Zero is given as the value for a keyword in the keyword list. Action: SJREKERR contains the address of the keyword. Change the zero to a valid value.
0C	000	Meaning: System error. The system could not obtain storage for this request. Action: Inform your system programmer of this problem.
10	000	Meaning: System error. The ESTAE-type recovery routine failed. Action: Inform your system programmer of this problem.
14	000	Meaning: System error. SJF encountered a condition that caused an abnormal termination. Action: Check the input parameters, particularly any pointer fields, to determine if the input values are correct.
18	000	Meaning: System error. The service routines for SJFREQ are not available. Action: SJF did not initialize properly. Contact the appropriate IBM support personnel.