Preparing to use VERIFY for validating and building text units

An application programmer should consider several things in order to code an application correctly when using VERIFY. These items are listed here and described in the following paragraphs.

Error Information
Parameter Delimiters
Sequence of Parameter Validation
Operand Processing
Parameter Overrides
Last Call Processing
Using the SJF Environment
Text Unit Output Area
Prefixing Data Set Names

Error information: When VERIFY is passed a subparameter or sublist element, VERIFY validates the syntax. If the subparameter or sublist element is correct, VERIFY builds a text unit to represent it. If the subparameter or sublist element is not valid, VERIFY returns information indicating the data was not valid. The reason code identifies the type of error. For some errors VERIFY returns error message text and an operand description. The application can use the text and description to inform the user how to correct the error. See z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO for the message text and operand descriptions.

Parameter delimiters: VERIFY does not process the parentheses or commas that might appear in the input as delimiters. The application must parse the statement and identify the input VERIFY is to process. Input passed to VERIFY must not include enclosing quotation marks. If the input is enclosed in quotation marks and contains two consecutive single quotation marks, the application must:

Convert the consecutive single quotation marks to a single quotation mark
Remove the enclosing quotation marks
Pass the input to VERIFY.

For example, pass the string 'BOARD''S' as BOARD'S to VERIFY as the value to process.

VERIFY provides two functions whose use is determined by whether the input value is delimited by single quotation marks. When an input value is delimited by single quotation marks and an application sets parameter field SJVEQUOT on (sets it to one), VERIFY does additional validation. VERIFY determines if the input value may be specified within quotation marks on the statement. If an application does not want to use the quotation mark validation feature, it should set SJVEQUOT to zero.

When an input value is not delimited by single quotation marks and an application specifies a value in SJVEPRFX, VERIFY performs a function called prefixing.

Sequence of parameter validation: For a keyword operand, an application must call VERIFY for each subparameter and sublist element. Call VERIFY with the subparameters and sublist elements in the order in which they appear following the keyword operand. For example, in Validate and build a text unit for a keyword operand and subparameters the application calls VERIFY for the subparameter GT10, and then calls VERIFY again to process the subparameter GB10. The application must call VERIFY once for each subparameter.

If an application passes VERIFY a subparameter or sublist element that is not valid, VERIFY must be called again for the same subparameter or sublist element until the application does one of the following:

Passes a valid subparameter or sublist element
Passes a new operand or keyword operand value
Requests last call
Issues a SJFREQ TERMINATE request.

In the case of a subparameter or sublist element that is not correct, the application could prompt its user for a valid value. If the application is unable to produce a valid value, VERIFY processes no more subparameters or sublist elements for the keyword operand; VERIFY builds text units for the subparameters and sublist elements previously processed for the keyword operand. If this is the first subparameter and the first sublist element, and the caller cannot produce a valid value, VERIFY builds no text units for the keyword operand.

Operand processing: Operands are stand-alone words specified on a statement. However, if an application wants a text unit built for an operand, it must pass VERIFY a null subparameter with the operand. The subparameter must be specified as follows:

1 as the subparameter number
0 as the subparameter length.

If an application does not specify an operand with a subparameter, VERIFY validates the operand, but does not build a text unit.

Parameter overrides: Operands or keyword operands may be processed in any order. When an application specifies the same keyword operand more than once, the text unit represents the last value VERIFY validated for the keyword operand. For example, an application issues the statement below. Assume that the application requests VERIFY to process NOTIFY(ALB18.POST) after NOTIFY(NYS24.BENCH,NYS24.PARKER)

OUTDES out1 NOTIFY(NYS24.BENCH,NYS24.PARKER) NOTIFY(ALB18.POST)

When VERIFY completes processing of the statement, the text unit represents (ALB18.POST) as the value for the NOTIFY keyword operand.

Last call processing: When the application has processed all the statement information, it must call VERIFY using the last call indicator. See Requesting last call for an example that specifies last call. This call signifies that no more operands or keyword operands are to be processed for the current statement. After this call, the text units and text unit pointer list for the current statement are available for the application to use. Also, the SJF environment has been refreshed so VERIFY can process another statement with the same environment. (SJVENOCU must have been set on to save the environment.) To invoke VERIFY and request last call, use the parameter list returned from the previous call, and set SJVELSTC on. Setting SJVELSTC on and calling VERIFY makes the text units available for use. This is an additional call after the last subparameter or sublist element is processed. No text units are built on this call.

Using the SJF environment: If an application requests VERIFY to build text units, the application must reuse the SJF environment until a complete statement is verified. So the application must supply the same value in SJVESTOR on each call after the first. VERIFY builds the text units in the area addressed by SJVESTOR. If the application wants to use the same environment to process another OUTDES statement with VERIFY, the application must indicate last call (set SJVELSTC) when VERIFY completes processing the first statement. After the application indicates last call, the application can call VERIFY to process another statement.

Text unit output area: When calling VERIFY to validate information and build text units, the application must pass VERIFY a pointer to an output area to hold the text units. This output area is referred to as the SJF VERIFY text unit output area. Pass the pointer to the output area in SJVETUBP and the length of the output area in SJVETUBL.

An application using the SJFREQ VERIFY service to validate multiple subparameters on one keyword operand must make sure to specify the same SJF VERIFY text unit output area in parameter list field SJVETUBP for each call.

The length of the VERIFY text unit output area must be at least 256 bytes plus area needed to contain the text units built for the statement. A work area of 1K is large enough for any set of text units.

If an application needs to provide additional work areas to contain the text units, the additional work areas can be of any length that will contain at least the text unit VERIFY builds. If more space is needed in the VERIFY text unit output area, VERIFY returns return code 4 and reason code 4B2, indicating the problem. The application must:

Obtain more storage and call VERIFY again
Pass the new pointer (SJVETUBP) and text unit output area length (SJVETUBL)
Pass the subparameter or sublist element that was not processed in the last request.

When an application wants to use the same output area to process multiple keyword operands, the application can request that VERIFY return in parameter field SJVETUBS the amount of output area used by doing the following:

Set SJVERSBS on.
Pass the same value in parameter field SJVETUBP as on the initial call for this statement. This value is the pointer to the text unit output area.

If the application uses VERIFY to validate the same statement and specifies a different value in SJVETUBP and SJVERSBS is on, the reason code SJRCIVBD is set. The application specified that the same output area be used on multiple calls by setting SJVERSBS on, but proceeded to specify another output area to be used.

Prefixing data set names: Some keyword operands require a data set name as a subparameter. Data set names may be fully qualified (delimited by single quotation marks) or unqualified (not delimited by single quotation marks). For unqualified data set names, VERIFY allows an application to indicate a prefix in parameter field SJVEPRFX. VERIFY uses this prefix as the first qualifier for the unqualified data set name on the keyword operands for which VERIFY allows prefixing. To indicate a prefix, specify a value in SJVEPRFX and set SJVEQUOT to zero.