JOB-VARIABLES

File 82
Op-Sys BS2000/OSD
Statement PROCESS, FIND
Task Perform various job variable functions, for example, define and delete job variables, query and change job variable values.

Common Fields for all Operating Systems

Dictionary Field Name F/L Mu DE Remarks
ERROR-CODE N3      
ERROR-TEXT A58      
NODE N5   D  
NODE-NAME A16   D  
SYSTEM-MESSAGE-CODE A10      
SYSTEM-CODE B2      
FUNCTION A8   D Required.
NAME A54   D Required.
SECOND-NAME A54   D Relevant with FUNCTION=WRITE or MODATTR only.
ACCESS A5   D Relevant with FUNCTION=MODATTR, ALLOC, ATTRIB.
SHARE A3   D Relevant with FUNCTION=MODATTR, ALLOC, ATTRIB.
READ-PASSWORD A8   D Relevant with FUNCTION=MODATTR, ALLOC, ATTRIB, WRITE.
WRITE-PASSWORD A8   D Relevant with FUNCTION=MODATTR, ALLOC, ATTRIB.
RETENTION-PERIOD N5   D Relevant with FUNCTION=MODATTR.
SUBSTRING-START N3   D Relevant with FUNCTION=WRITE or READ only.
SUBSTRING-LENGTH N3   D Relevant with FUNCTION=WRITE or READ only.
CREATION-DATE A8   D Relevant with FUNCTION=ATTRIB only.
EXPIRATION-DATE A8   D Relevant with FUNCTION=ATTRIB only.
JV-TYPE A10     Relevant when FUNCTION=ATTRIB.
LENGTH N3   D Relevant when FUNCTION=ATTRIB, READ, WRITE.
DATA A253   D Relevant when FUNCTION=READ or WRITE.
DATA-APPENDIX A3   D Relevant when FUNCTION=READ or WRITE.
PASSWORD A8   D Relevant with all functions except ATTRIB.
CREATION-DATX D     Relevant when FUNCTION=ATTRIB.
EXPIRATION-DATX D     Relevant when FUNCTION=ATTRIB.
REPLACE A3   D Relevant when FUNCTION=ALLOC.
FROM-SUBSTRING-START N3   D Relevant when FUNCTION=WRITE.
FROM-SUBSTRING-LENGTH N3   D Relevant when FUNCTION=WRITE.

Relevant Error Codes

Code Text BS2000/OSD
530 Access denied by Security Facility. X
531 Password missing or incorrect. X
600 Unknown function. X
626 DATA missing. X
699 Not enough main storage available. X
733 User ID does not exist. X
747 LENGTH or SUBSTRING-LENGTH invalid. X
756 Job variable name missing or invalid. X
798 Task was not started under TSOS. X
799 Entire System Server internal error. X
987 Job Variable already exists. X
992 Requested job variable not found. X

Field Descriptions

Field Name Type/Length Operating System
ACCESS (A5)  

Specifies whether access to the job variable is READ or WRITE. WRITE is the default. Valid with FUNCTION=MODATTR as input field. With ALLOC and ATTRIB, it is an output field.

Field Name Type/Length Operating System
CREATION-DATE (A8)  

Only for FUNCTION=ATTRIB: The creation date of the job variable.

Field Name Type/Length Operating System
CREATION-DATX (D)  

Creation date in Natural format.

Field Name Type/Length Operating System
DATA (A253)  

Usage of this field depends on the function.

When FUNCTION=READ, contents of job variable or part of it (substring).

When FUNCTION=WRITE, value to be written (it is also possible to copy contents or substring from another job variable instead of data. Fields SECOND-NAME, FROM-SUBSTRING-START, FROM-SUBSTRING-LENGTH are relevant in this case).

Field Name Type/Length Operating System
DATA-APPENDIX (A3)  

This field contains bytes 254-256 of job variable. Refer to DATA field for more details.

Field Name Type/Length Operating System
EXPIRATION-DATE (A8)  

Only for FUNCTION=ATTRIB: The date after which the job variable can be erased.

Field Name Type/Length Operating System
EXPIRATION-DATX (D)  

Expiration date in Natural format.

Field Name Type/Length Operating System
FROM-SUBSTRING-LENGTH (N3)  

Only for function WRITE: Length of substring to be copied from job variable specified in SECOND-NAME. Required if FROM-SUBSTRING-START is specified.

Field Name Type/Length Operating System
FROM-SUBSTRING-START (N3)  

Only for function WRITE: Start of substring to be copied from job variable specified in SECOND-NAME. If this is omitted, the entire job variable is copied.

Field Name Type/Length Operating System
FUNCTION (A8)  

Function to be performed. Possible options:

Option Explanation
ALLOC Define a job variable.
ATTRIB Retrieve information about a job variable.
DELETE Delete a job variable.
LIST Retrieve list of job variables (only NAME is valid for this function).
MODATTR Modify characteristics of a job variable.
READ Read value of a job variable.
WRITE Set value of of a job variable, or copy from one job variable to another.
Field Name Type/Length Operating System
JV-TYPE (A10)  

The type of job variable is returned in this field when FUNCTION=ATTRIB. Possible values are NUMERIC, NON-NUMERIC.

Field Name Type/Length Operating System
LENGTH (N3)  

Usage of this field depends on the function.

When FUNCTION=ATTRIB, the size of the job variable (length of JV value).

When FUNCTION=READ, real length of data read.

When FUNCTION=WRITE, length of data to be written. This can also be specified in the field SUBSTRING-LENGTH. If DATA is given, both can be omitted.

Note:
SUBSTRING-START + LENGTH must not exceed 257.

Field Name Type/Length Operating System
NAME (A54)  

Name of the job variable to be handled. With function LIST, the name can contain wildcards, but a name cannot start with an asterisk *. Wildcards in catalog ID or user ID of the JV name are only allowed for user TSOS.

Field Name Type/Length Operating System
PASSWORD (A8)  

Valid for all functions except FUNCTION=ATTRIB. If the job variable specified in NAME is password-protected, the appropriate password must be specified here.

Field Name Type/Length Operating System
READ-PASSWORD (A8)  

Usage of this field depends on the function. Possible values:

When FUNCTION=ATTRIB:

Value Explanation
NONE No password is defined.
YES Read password is defined for job variable. If caller is TSOS and Entire System Server is running under TSOS, the password itself is returned.

When FUNCTION=ALLOC or MODATTR:

Value Explanation
blank Default. No read password.
password New read password to be defined for job variable
*NONE Reset existing password.

When FUNCTION=WRITE:

When copying from another job variable which is password-protected, the appropriate password for that job variable.

Field Name Type/Length Operating System
REPLACE (A3)  

Only for function ALLOC. Possible values:

Value Explanation
IGN Default. Allocate job variable if it does not already exist and ignore allocate for existing job variable (corresponds to BS2000/OSD command DCLJV).
NO Allocate job variable only if it does not already exist. If it already exists, Error 987 is returned.
YES Allocate job variable and replace any existing job variable with the same name. The existing job variable is erased before allocation.
Field Name Type/Length Operating System
RETENTION-PERIOD (N5)  

Only for FUNCTION=MODATTR. Specifies how many days the job variable must remain unchanged.

Field Name Type/Length Operating System
SECOND-NAME (A54)  

When FUNCTION=MODATTR, new name when renaming job variable. No user ID can be specified.

When FUNCTION=WRITE, input name when copying job variable.

Field Name Type/Length Operating System
SHARE (A3)  

Specifies whether the job variable is accessible to other users.

Valid with FUNCTION=MODATTR as input field.

The value is returned with FUNCTION=ATTRIB or ALLOC. Possible options:

Option Explanation
NO Default. The job variable is not accessible to other users.
YES The job variable is accessible to other users.
Field Name Type/Length Operating System
SUBSTRING-LENGTH (N3)  

Usage of this field depends on the function.

When FUNCTION=READ, the length of substring to be read.

When FUNCTION=WRITE, the length of the substring to be written. This can also be specified in the field LENGTH. If DATA is given, both can be omitted.

Note:
SUBSTRING-START + SUBSTRING-LENGTH must not exceed 257.

Field Name Type/Length Operating System
SUBSTRING-START (N3)  

Valid only with FUNCTION=READ or WRITE. Start position of substring, if only substring of the job variable is to be read or written. Maximum value is 256.

Field Name Type/Length Operating System
WRITE-PASSWORD (A8)  

Usage of this field depends on the function. Possible values:

When FUNCTION=ATTRIB:

Value Explanation
NONE No password is defined.
YES Write password is defined for job variable. If caller is TSOS and Entire System Server is running under TSOS, the password itself is returned.

When FUNCTION=ALLOC or MODATTR:

Value Explanation
blank Default. No write password.
password New write password to be defined for job variable.
*NONE Reset existing password.