SJFREQ VERIFY service

SJFREQ VERIFY service

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

Use VERIFY to validate and build text units to represent an OUTDES statement, its operands, subparameters and sublist elements. The OUTDES information corresponds to SJF-defined information on the OUTPUT JCL statement. If you do not specify correctly the input subparameter data, VERIFY returns an error message.

SJFREQ VERIFY input parameters

For each SJFREQ invocation, you need to initialize certain fields of parameter list IEFSJVEP. See SJVEP in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for the mapping provided by the IEFSJVEP mapping macro. The list of parameters and descriptions of their values are below, followed by Table 1 that summarizes the required parameter fields for the three SJFREQ VERIFY functions.

VERIFY performs three functions. Use Table 1 to determine the required parameters for the SJFREQ VERIFY function you want to request. The table gives details about the required values.

SJVEID

The identifier ‘SJVE’ of the VERIFY parameter list. Assign the symbolic equate SJVECID to this field.

SJVEVERS

The current version number of the SJFREQ VERIFY parameter list. Assign the symbolic equate SJVECVER to this field.

SJVEFLAG

The environment control flag.

SJVENOCU: Indicates whether the SJF environment is preserved from call to call or obtained for each call. Parameter SJVESTOR references the environment. When set to 0, the environment is obtained for each call. When set to 1, the environment is preserved.
SJVEUNAU: Indicates whether the caller is unauthorized. If an application makes repetitive service calls using the same SJF environment, the authorization must be same for each call.

SJVELEN

The length of the VERIFY parameter list (IEFSJVEP). Assign the symbolic equate SJVELGTH to this field.

SJVESTOR

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

SJVEJDVT

Enter zero for this field on input. If a value is returned in the field, use the returned value for subsequent uses of the service.

SJVECMND

The name of the statement that contains the output descriptor information. Specify the statement name OUTDES in an 8-character field, left-justified, and padded with blanks.

SJVEOPEP

The pointer to the operand or keyword operand to be validated. This field should contain an address of the first byte of the operand or keyword operand. Set the length of the operand in SJVEOPEL. Zero is a valid value when specifying just the statement name as specified in SJVECMND.

SJVEOPEL

The length of the operand or keyword operand to be validated. This field should contain the actual length of the operand or keyword operand pointed to by SJVEOPEP.

SJVEPARM

The subparameter number representing the subparameter to be validated. Set this value to one whenever validating an operand. When validating a keyword operand, set this to the correct subparameter number.

SJVESUBL

The sublist element number representing the sublist element to be validated. This field should be set to zero if the subparameter is not a sublist.

SJVEPRMP

The pointer to the subparameter or sublist element to be validated. Set the length of the subparameter or sublist element in SJVEPRML.

SJVEPRML

The length of the subparameter or sublist element pointed to by SJVEPRMP. This field should contain the actual length of the subparameter or sublist element pointed to by SJVEPRMP.

SJVETUBL

The length of the text unit output area. The field should contain the length of the output area pointed to by SJVETUBP. The minimum you should specify for the output area is 256 bytes plus sufficient storage to accommodate the text units that will be built as a result of your VERIFY request. A work area of 1K is large enough for any set of text units to be built.

SJVETUBP

The pointer to the text unit output area. The output area will contain the text unit pointer list and text units upon return from the VERIFY service call. If the output area is not large enough to hold all the text units and the text unit pointer list, you can point to and use an additional output area. When using additional output areas, the original output area must be accessible to SJF; it cannot be freed or changed. Set the length of the output area in SJVETUBL.

SJVEFLG1

The VERIFY option flag.

SJVELSTC

Indicates last call for the text units being built. Set this indicator to one for the last VERIFY call. Setting this indicator on makes the text units available for use.

SJVERSBS

Indicates that the same text unit output area is to be used for multiple calls. SJVETUBS contains the returned length of the area the service used to build the text units and text unit pointer list. When this indicator is on, SJVETUBP must be the same for each VERIFY call.

SJVEQUOT

Indicates that a subparameter was specified in quotation marks. To allow quotation marks on all subparameters, the caller can set this bit to zero. Note that some subparameters do not allow quotation marks. For any value specified in quotation marks, the caller should have:

Removed the delimiting quotation marks
Converted two consecutive single quotation marks to one single quotation mark.

SJVEPRFX

The prefix to be concatenated to a subparameter that is a data set name. This field is not used if SJVEQUOT is on or if the subparameter is not defined as allowing unqualified data set names. If no prefix is specified, this field must be set to zero.

Table 1. Required Fields for SJFREQ VERIFY Functions
IEFSJVEP parameter list field	Validate a subparameter or sublist element and build a text unit	Validate an operand or keyword operand	Validate a statement name
SJVEID	Symbolic equate SJVECID	Symbolic equate SJVECID	Symbolic equate SJVECID
SJVEVERS	Symbolic equate SJVECVER	Symbolic equate SJVECVER	Symbolic equate SJVECVER
SJVENOCU	Set to indicate if the SJF environment should be reused.	Set to indicate if the SJF environment should be reused.	Set to indicate if the SJF environment should be reused.
SJVEUNAU	Set to indicate if the caller is authorized.	Set to indicate if the caller is authorized.	Set to indicate if the caller is authorized.
SJVELEN	Symbolic equate SJVELGTH	Symbolic equate SJVELGTH	Symbolic equate SJVELGTH
SJVESTOR	Local working storage pointer or zero	Local working storage pointer or zero	Local working storage pointer or zero
SJVECMND	Statement name associated with the operand for which the subparameter or sublist is to be validated.	Statement name associated with the operand to be validated.	Statement name to be validated.
SJVEOPEP	Address of the field that contains the subparameter or sublist element to be validated.	Address of the field that contains the operand or keyword operand to be validated.	zeros
SJVEOPEL	Length of the field that contains the subparameter or sublist element (SJVEOPEP).	Length of the field that contains the operand or keyword operand to be validated (SJVEOPEP).	not used
SJVEPARM	Number of the subparameter to be verified (1 for the first, 2 for the second, . . .)	zeros	zeros
SJVESUBL	If the subparameter to be verified is a sublist, specify the number of the sublist element (1 for the first, 2 for the second,. . .). If the subparameter is not a sublist, specify zero.	not used	not used
SJVEPRMP	Address of the field with the subparameter or sublist to be verified.	not used	not used
SJVEPRML	Length of the subparameter or sublist to be verified.	not used	not used
SJVETUBL	Length of the SJFREQ VERIFY workarea.	not used	not used
SJVETUBP	Pointer to the SJFREQ VERIFY workarea.	not used	not used
SJVELSTC	Last call bit	not used	not used
SJVEQUOT	Subparameters can be specified in quotation marks.	not used	not used
SJVERSBS	Text unit buffer is to be used for multiple calls.	not used	not used
SJVEPRFX	Prefix to be concatenated to a subparameter.	not used	not used

SJFREQ VERIFY output parameters

Data for an SJFREQ VERIFY function is returned in several fields of the IEFSJVEP parameter list. The list of output parameters and their descriptions are below, followed by Table 2 that summarizes the output parameters returned for each of the three SJFREQ VERIFY functions.

SJVEREAS: The reason code returned from VERIFY processing. See Return and reason codes with related message text for information about specific reason codes.
SJVEJDVT: If the caller specified zero on input, this field contains the default JDVT name. Otherwise, the value in this field will be the same as it was on input.
SJVETUBS: The length of the storage used in the text unit output area to build the text unit pointer list and text units. This field is filled in only when SJVERSBS is set on. The text unit output area is referenced by fields SJVETUBL and SJVETUBP.
SJVETUPL: The pointer to the beginning of the text unit pointer list in the text unit output area.
SJVEOPD: The SJF description of the operand or keyword operand that was referenced on input by the fields SJVEOPEP and SJVEOPEL. Applications can use information in this field in messages to their application users in place of the operand or keyword operand. Refer to Operand descriptions for the operands and their descriptions. VERIFY returns a value in this field for return code 0 and reason codes with return code 4.
SJVEOPDL: The length of the operand or keyword operand description returned in field SJVEOPD.
SJVEMSGL: The length of the message information returned in SJVEMSG.
SJVEMSG: This field contains a message that indicates the correct syntax for the subparameter or sublist element that is in error. The subparameter or sublist element is referenced by the input fields SJVEPRMP and SJVEPRML. VERIFY returns a value in this field for return code 4 with some reason codes. Refer to Return and reason codes with related message text for the actual message text VERIFY returns.

When an application receives a return code of 0 or 4, VERIFY returns values in the parameter list fields indicated below. The table is organized by function and return code. VERIFY does not fill in any output parameter list fields when it returns a return code 8 or above.

Table 2. SJFREQ VERIFY Output Fields
IEFSJVEP parameter list field	Validate a subparameter or sublist element and build a text unit Return Code 0	Validate a subparameter or sublist element and build a text unit Return Code 4	Validate an operand or keyword operand Return Code 0	Validate an operand or keyword operand Return Code 4	Validate a statement name Return Code 0	Validate a statement name Return Code 4
SJVEREAS	Value returned	Value returned	Value returned	Value returned	Value returned	Value returned
SJVEJDVT	Value returned	Value returned	Value returned	Value returned	Value returned	Value returned
SJVETUBS	Value returned only when SJVERSBS is set to 1.	—	—	—	—	—
SJVETUPL	Value returned	Value returned for some reason codes.	—	—	—	—
SJVEOPD	Value returned	Value returned for some reason codes.	Value returned	—	—	—
SJVEOPDL	Value returned	Value returned for some reason codes.	Value returned	—	—	—
SJVEMSGL	—	Value returned for some reason codes.	—	—	—	—
SJVEMSG	—	Value returned for some reason codes.	—	—	—	—

Operand descriptions

Operand descriptions appear in parameter list field SJVEOPD as indicated in Table 2. The table that follows lists the operands, keyword operands and their descriptions.

Table 3. SJF Operand and Keyword Operand Descriptions. These descriptions appear in parameter field SJVEOPD.
Operand or Keyword Operand	Description
ADDRESS	ADDRESS FOR SEPARATOR PAGE
BUILDING	BUILDING ID
BURST	BURSTER TRIMMER STACKER
NOBURST	BURSTER TRIMMER STACKER
CHARS	CHARACTER ARRANGEMENT TABLE
CKPTLINE	CHECKPOINT LINES
CKPTPAGE	CHECKPOINT PAGES
CKPTSEC	CHECKPOINT SECONDS
CLASS	OUTPUT CLASS
COMPACT	COMPACTION TABLE NAME
CONTROL	CARRIAGE CONTROL
COPIES	NUMBER OF COPIES
COPYCNT	NUMBER OF COPIES
DATACK	DATA CHECK
DEFAULT	DEFAULT OUTPUT DESCRIPTOR
NODEFAULT	DEFAULT OUTPUT DESCRIPTOR
DEPT	DEPARTMENT ID
DEST	OUTPUT DESTINATION
DPAGELBL	DATA PAGE LABEL
NODPAGELBL	DATA PAGE LABEL
FCB	FORMS CONTROL IMAGE
FLASH	FORMS OVERLAY
FORMDEF	FORM DEFINITION MEMBER NAME
FORMS	PRINT FORMS
GROUPID	OUTPUT GROUP IDENTIFIER
INDEX	RIGHT PRINT POSITION INDEX
LINDEX	LEFT PRINT POSITION INDEX
LINECT	LINE COUNT
MODIFY	COPY MODIFICATION MODULE
NAME	NAME OF SYSOUT OWNER
NOTIFY	DESTINATION FOR PRINT COMPLETE MESSAGES
OUTBIN	PRINTER OUTPUT BIN ID
OUTDISP	SYSOUT DISPOSITION
PAGEDEF	PAGE DEFINITION MEMBER NAME
PIMSG	PRINTER INFORMATION MESSAGES
PRMODE	PROCESS MODE
PRTY	OUTPUT PRIORITY
ROOM	ROOM IDENTIFICATION
SYSAREA	SYSTEM PRINTABLE AREA
NOSYSAREA	SYSTEM PRINTABLE AREA
THRESHLD	MAXIMUM LINES OF OUTPUT
TITLE	NAME FOR SEPARATOR PAGE
TRC	TABLE REFERENCE CHARACTER
NOTRC	TABLE REFERENCE CHARACTER
UCS	UNIVERSAL CHARACTER SET
USERLIB	USER SPECIFIED AFP RESOURCE LIBRARIES
WRITER	EXTERNAL WRITER NAME

ABEND codes

SJFREQ VERIFY might abnormally terminate with abend code X'054'. See z/OS MVS System Codes for an explanation and programmer response.

Return and reason codes with related message text

SJFREQ VERIFY return codes appear in register 15. When SJFREQ returns control to your program, SJVEREAS contains a reason code. 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. Message text returned in field SJVEMSG appears with the meanings and actions for the related reason codes. Italics indicates variable parts of the message. Words in bold print indicate that VERIFY selects among those choices before returning the message.

For return code 4, reason codes 1F4 - 204, 226, and 4B3, the subparameter or sublist element referenced in SJVEPRMP and SJVEPRML is not correct. For each of these conditions, a description of the correct specification of the field is returned in SJVEMSG. The related message text appears with the appropriate reason codes that follow. SJVEOPD contains a description of the operand or keyword operand. Table 3 lists the operands and keyword operands and their descriptions.

Table 4. Return and Reason Codes for the SJFREQ Macro VERIFY Service
Return Code	Reason Code	Meaning and Action
0	000	Meaning: VERIFY processing completed successfully. Action: None.
04	004	Meaning: Program error. The VERIFY request was not processed. The value specified in SJVEJDVT is not valid. Action: Set SJVEJDVT to hexadecimal zeros or to the value returned on the previous call.
04	005	Meaning: System error. The information referenced by parameter field SJVEJDVT does not exist. Action: SJF did not initialize properly. Contact the appropriate IBM® support personnel.
04	0CB	Meaning: Program error. SJF does not recognize the subparameter specified in SJVEPARM. Action: Check the number of subparameters allowed and the value specified in SJVEPARM.
04	0CF	Meaning: Program error. The command specified in SJVECMND is not recognized by SJF. Action: Check the spelling and specification (left-justified, padded with blanks) of the value specified in SJVECMND.
04	0D0	Meaning: Program error. The operand or keyword operand indicated by fields SJVEOPEP and SJVEOPEL is not recognized by SJF. Action: Check the specified length and the spelling of the operand or keyword operand. Make sure SJVEOPEP is a pointer value.
04	1F4	Meaning: Program error. The length of a specified subparameter or sublist element as specified in SJVEPRML is not valid. Action: Check the subparameter or sublist element length specified in SJVEPRML and the allowable subparameter or sublist element length. Message text: VALUE MUST BE 1 CHARACTER VALUE MUST BE `n` CHARACTERS VALUE MUST BE `minimum length` TO `maximum length` CHARACTERS If an error occurs involving a subparameter that is a data set name and the application specified a prefix, and SJVEQUOT is off (0), the following message might be added to the above message text. VALUE NOT ENCLOSED IN QUOTES IS CONCATENATED TO PREFIX `value in SJVEPRFX`.
04	1F5	Meaning: Program error. A subparameter that was specified is not a valid choice. Action: Specify one of the allowable subparameters for the keyword operand. Message text: VALUE MUST BE `choice1`. . .OR `choice n`
04	1F6	Meaning: Program error. A numeric subparameter or sublist element exceeds the maximum allowable value. Action: Check the values specified in SJVEPRMP and SJVEPRML and the allowable value for this subparameter or sublist element. Message text: VALUE MUST BE IN THE RANGE OF `minimum value` TO `maximum value`
04	1F7	Meaning: Program error. A numeric subparameter or sublist element is less than the minimum allowable value. Action: Check the values specified in SJVEPRMP and SJVEPRML and the allowable value for this subparameter or sublist element. Message text: VALUE MUST BE IN THE RANGE OF `minimum value` TO `maximum value`
04	1FA	Meaning: Program error. No subparameter or sublist element was specified for the keyword operand. Action: Specify a value in SJVEPRML. Message text: VALUE MUST BE 1 LEVEL VALUE MUST BE 1 TO `maximum number of levels` LEVELS VALUE MUST BE 1 TO `maximum number of levels` LEVELS WITH 1 TO `maximum level length` CHARACTERS IN EACH LEVEL VALUE MUST BE 1 CHARACTER VALUE MUST BE `n` CHARACTERS VALUE MUST BE `minimum length` TO `maximum length` CHARACTERS If an error occurs involving a subparameter that is a data set name and the application specified a prefix, and SJVEQUOT is off (0), the following message might be added to the above message text. VALUE NOT ENCLOSED IN QUOTES IS CONCATENATED TO PREFIX `value in SJVEPRFX`. VALUE MUST BE `choice1`. . .OR `choice n` VALUE MUST BE HEXADECIMAL CHARACTER, CHARACTERS VALUE MUST BE NUMERIC CHARACTER VALUE MUST BE NUMERIC CHARACTERS PRINTABLE CHARACTER, CHARACTERS VALUE MUST BE SPECIFIED WITH THE `keyword` KEYWORD
04	1FE	Meaning: Program error. The subparameter or sublist element level length exceeds the maximum allowed for character data. Action: Check the value in SJVEPRML. Message text: VALUE MUST BE 1 LEVEL VALUE MUST BE 1 TO `maximum number of levels` LEVELS VALUE MUST BE 1 TO `maximum number of levels` LEVELS WITH 1 TO `maximum level length` CHARACTERS IN EACH LEVEL If an error occurs involving a subparameter that is a data set name and the application specified a prefix, and SJVEQUOT is off (0), the following message might be added to the above message text. VALUE NOT ENCLOSED IN QUOTES IS CONCATENATED TO PREFIX `value in SJVEPRFX`.
04	1FF	Meaning: Program error. The number of levels for a subparameter or sublist element exceeds the maximum allowed. Action: Check the value pointed to by SJVEPRMP. Message text: VALUE MUST BE 1 LEVEL VALUE MUST BE 1 TO `maximum number of levels` LEVELS VALUE MUST BE 1 TO `maximum number of levels` LEVELS WITH 1 TO `maximum level length` CHARACTERS IN EACH LEVEL If an error occurs involving a subparameter that is a data set name and the application specified a prefix, and SJVEQUOT is off (0), the following message might be added to the above message text. VALUE NOT ENCLOSED IN QUOTES IS CONCATENATED TO PREFIX `value in SJVEPRFX`.
04	200	Meaning: Program error. The first character of the level in the subparameter or sublist element is not valid for character data. Action: Check the value pointed to by SJVEPRMP. Message text: VALUE MUST BE ALPHABETIC, NUMERIC, NATIONAL, OR `list of special characters` FIRST CHARACTER VALUE MUST BE ALPHABETIC, NUMERIC, NATIONAL, OR `list of special characters` CHARACTER VALUE MUST BE ALPHABETIC, NUMERIC, NATIONAL, OR `list of special characters` CHARACTERS VALUE CONTAINS INVALID FIRST CHARACTER If an error occurs involving a subparameter that is a data set name and the application specified a prefix, and SJVEQUOT is off (0), the following message might be added to the above message text. VALUE NOT ENCLOSED IN QUOTES IS CONCATENATED TO PREFIX `value in SJVEPRFX`.
04	201	Meaning: Program error. A character other than the first character of the level in the subparameter or sublist element is not valid for character data. Action: Check the value pointed to by SJVEPRMP. Message text: VALUE MUST BE ALPHABETIC, NUMERIC, NATIONAL OR, `list of special characters` CHARACTERS OTHER THAN THE FIRST VALUE MUST BE ALPHABETIC, NUMERIC, NATIONAL, OR `list of special characters` CHARACTER VALUE MUST BE ALPHABETIC, NUMERIC, NATIONAL, OR `list of special characters` CHARACTERS If an error occurs involving a subparameter that is a data set name and the application specified a prefix, and SJVEQUOT is off (0), the following message might be added to the above message text. VALUE NOT ENCLOSED IN QUOTES IS CONCATENATED TO PREFIX `value in SJVEPRFX`.
04	202	Meaning: Program error. The level specification is not valid. Action: Check the value pointed to by SJVEPRMP. Message text: VALUE MUST BE 1 LEVEL VALUE MUST BE 1 TO `maximum number of levels` LEVELS VALUE MUST BE 1 TO `maximum number of levels` LEVELS WITH 1 TO `maximum level length` CHARACTERS IN EACH LEVEL If an error occurs involving a subparameter that is a data set name and the application specified a prefix, and SJVEQUOT is off (0), the following message might be added to the above message text. VALUE NOT ENCLOSED IN QUOTES IS CONCATENATED TO PREFIX `value in SJVEPRFX`.
04	203	Meaning: Program error. Nonhexadecimal characters were specified for a subparameter or sublist element. Action: Check the value pointed to by SJVEPRMP.
04	204	Meaning: Program error. Nonnumeric characters were specified for a subparameter or sublist element. Action: Check the value pointed to by SJVEPRMP. Message text: VALUE MUST BE NUMERIC CHARACTER, CHARACTERS
04	226	Meaning: Program error. A text character that was specified for a subparameter or sublist element is not valid. Action: Check the value pointed to by SJVEPRMP. Message text: VALUE MUST BE PRINTABLE CHARACTER, CHARACTERS
04	229	Meaning: A keyword operand specified was not a valid choice. Action: Specify one of the allowable keyword operands. Message text: VALUE IS NOT AN ALLOWABLE KEYWORD OPERAND
04	4B0	Meaning: Program error. No statement was specified. The value specified for SJVECMND is zero. Action: Specify a statement in SJVECMND.
04	4B1	Meaning: Program error. No address was specified in SJVETUBP for the text unit output area. Action: Specify a value in SJVETUBP.
04	4B2	Meaning: Program error. There is not enough storage in the text unit output area to construct the text unit for the current value. Action: Increase the size of the output area, adjust SJVETUBP and SJVETUBL, and call VERIFY again with the same input.
04	4B3	Meaning: Program error. A subparameter or sublist element cannot be specified in quotation marks. SJVEQUOT is set on, but quotation marks are not allowed for the specified subparameter or sublist element. Action: Either set SJVEQUOT off or specify a value for which quotation marks are allowed. Message text: VALUE CANNOT BE SPECIFIED IN QUOTES
04	4B4	Meaning: Program error. The text unit output area is different than the text unit output area passed on the first call. SJVETUBP has a different value than on the first call, and SJVERSBS is set on. SJF cannot obtain the amount of contiguous storage necessary for the text unit pointer list and text units when more than one buffer is provided. Action: Check the value in SJVETUBP.
08	000	Meaning: Program error. The input parameter list, IEFSJVEP, is not valid. Action: Check to see if SJVEID, SJVEVERS, or SJVELEN is incorrect and not recognized by SJF.
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.