Retrieve Change Request Description (QFVRTVCD) API


  Required Parameter Group:

1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
3 Format Input Char(8)
4 Qualified change request description name Input Char(20)
5 Activity name Input Char(10)
6 Error code I/O Char(*)

  Default Public Authority: *USE

  Threadsafe: No

The Retrieve Change Request Description (QFVRTVCD) API retrieves either general change request description information, or information pertaining to a single activity within the change request description.


Authorities and Locks

Change request description authority
*USE
Change request description lock
*SHRRD

Required Parameter Group

Receiver variable
OUTPUT; CHAR(*)

The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold. See CRQD0100 Format and CRQD0200 Format for descriptions of the formats.

Length of receiver variable
INPUT; BINARY(4)

The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.

Format
INPUT; CHAR(8)

The format of the data to return. The possible formats are:

CRQD0100 Returns general change request description information.
CRQD0200 Returns specific activity information for the specified change request description.

Qualified change request description name
INPUT; CHAR(20)

The qualified name of the change request description to retrieve information for. The Format is:

name CHAR(10)
library CHAR(10)
  Possible values: *LIBL, *CURLIB, library name.

Activity name
INPUT; CHAR(10)

The name of the activity to retrieve information for. This is ignored when the format parameter is CRQD0100.

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


CRQD0100 Format

See Field Descriptions for descriptions of the fields in this format.

Offset Type Field
Dec Hex
0 0 BIN(4) Bytes returned
4 4 BIN(4) Bytes available
8 8 CHAR(10) Qualified change request description name
18 12 CHAR(10) Qualified change request description library name
28 1C CHAR(10) Owner's profile
38 26 CHAR(10) User profile to run under
48 30 CHAR(6) Sequence number
54 36 CHAR(10) Problem ID
64 40 CHAR(21) Problem origin
85 55 CHAR(50) Text description


CRQD0200 Format

See Field Descriptions for descriptions of the fields in this format.

Offset Type Field
Dec Hex
0 0 BIN(4) Bytes returned
4 4 BIN(4) Bytes available
8 8 CHAR(10) Qualified change request description name
18 12 CHAR(10) Activity name
28 1C CHAR(10) Qualified change request description library name
38 26 CHAR(10) Activity type
48 30 CHAR(40) Start time
88 58 CHAR(10) Hold
98 62 CHAR(1) Destination of *LCL
99 63 CHAR(50) Activity text
149 95 CHAR(3) Reserved
152 98 BIN(4) CCSID of activity text description
156 9C BIN(4) Offset to node list name
160 A0 BIN(4) Number of nodes
164 A4 BIN(4) Offset to destination nodes
168 A8 BIN(4) Number of conditions
172 AC BIN(4) Offset to conditions
176 B0 BIN(4) Length of function parameters.
180 B4 BIN(4) Offset to function parameters.
184 B8 CHAR(*) Reserved
See note   CHAR(10) Node list name
See note   CHAR(10) Node list library name
See note   Array of CHAR(20) Destination nodes
See note   Array of CHAR(32) Conditions list
See note   CHAR(*) Function parameters
Note: The offset varies. This field is either optional or variable length. The offset is specified in a previous field. The data is left-justified with a blank pad at the end. The array of destination nodes and the array of conditions are returned in the same sequence they were entered.


Field Descriptions

Activity name. The name of the activity for which information is retrieved.

Activity text. The text description of the activity specified.

Activity type. The name of the activity type for this activity.

Bytes available. The number of bytes of data available to the calling program. The receiver variable could get this much data from this format if the receiver variable was this large or larger.

Bytes returned. The number of bytes of data that were returned to the calling program in the receiver variable. If this value is smaller than bytes available, there was more data than there was room for.

CCSID of activity text description. The coded character set identifies (CCSID) used for the activity text description.

Conditions list. The list of conditions that must be met before the activity can run. This is an array of up to 5 elements. The number of elements is specified by the number of conditions field. There can be up to 5 elements. If this data is not present, number of conditions and offset to conditions is 0.

Each element has the following format:

activity CHAR(10)
Activity name Possible values are: *PRV, user specified name.
relation CHAR(3)

The relational operator. Possible values are:

*EQ, *GT, *LT, *GE, *LE, *NE.
reserved CHAR(3)
code BIN(4)

The end code of conditioning activity. Valid values are 0-99. The following special values are also supported:

-1(*SUCCESS) The end code is any value from 0-9
-2(*FAIL) The end code is any value from 10-89
-3 (*NOTRUN) The end code is any value from 90-99.
-4 (*ANY) The end code is any value from 0-99.
mode CHAR(10)

Condition mode. Valid values are:

*ALLNODES All nodes of the conditioning activity must meet the completion criteria before this condition is considered met.
*SAMENODE Nodes of the conditioned activity need only wait for the same node of the conditioning activity to meet the completion criteria before this condition is considered met.
reserved CHAR(2).

Reserved for boundary alignment.

Destination is *LCL. Whether the destination for this activity is the local system. Possible values are Y and N.

Destination nodes. An array of elements. The number of elements is specified by the number of nodes field. There can be up to 50 elements. If number of nodes is 0, this field will not exist.

Each element has the following format:

Network ID CHAR(8)
Control point CHAR(8)
Reserved CHAR(4)

Function parameters. The structure is defined by the calling program.

Hold. Whether the activity is held when the change request is submitted. Possible values are:

*YES The activity is held when the change request is submitted. The user must release the activity before it will run.
*NO The activity is not held when the change request is submitted.

Length of function parameters. The length of the function parameters.

Node list name. The name of the node list. If no node list name exists, the offset to node list name is 0.

Node list library name. The library name of the node list.

Number of conditions. The number of conditions that must be satisfied before the activity can run. Possible values are 0 to 5. If no conditions are present, number of conditions and the offset to conditions are 0.

Number of nodes. The number of nodes in the destination nodes field. The possible values are 1 to 50.

Offset to conditions. If no conditions are present, number of conditions and the offset to conditions are 0.

Offset to destination nodes. The offset to the list of destination nodes.

Offset to function parameters. The offset to the function parameters.

Offset to node list name. Offset to the node list name. If this is 0, the node list name is not present.

Owner's profile. User profile that created the change request description object.

Problem ID. The ID of the problem associated with the change request description retrieved.

Problem origin. The origin system of the problem ID. The Format is:

Origin type CHAR(1)

Currently, the only value supported is A, which indicates the transport type is APPN.
Network ID CHAR(8)
Control point CHAR(8)
Reserved CHAR(4)

Qualified change request description name. The qualified name of the change request description object for which data is retrieved. The Format is:

Name CHAR(10)
Library CHAR(10)

Sequence number. The sequence number that is used to generate a generic activity name at the time an activity is added to the change request description.

Start time. The date and time window during which this activity can be started. The current date and time values and next date values are determined when the change request is submitted. The format is:

Start after time CHAR(10)

The time after which this activity may be started. Special values supported:

*CURRENT This activity may start any time on or after the time at which the change request was submitted.

Start after date CHAR(10)

The date after which this activity may be started. Special values supported:

*CURRENT This activity may start on any date on or after the date on which the change request was submitted.
*NEXT This activity may start on any date after the date on which the change request was submitted.

Start before time CHAR(10)

The time before which the activity must be started. If the activity cannot be started before this time then it is never started. Special values supported:

*ANY The activity may start any time on or after the start time.
*CURRENT The activity must start before the time the change request was submitted on the date specified on the start before date field.

Start before date CHAR(10)

The date before which the activity must be started. If the activity cannot be started by this date then it is never started. Special values supported:

*ANY The activity may start at any date on or after the start date.
*CURRENT The activity must start on the date the change request was submitted.
*NEXT The activity must start by the day after the date the change request was submitted.

The format of time is HHMMSS, where:

HH Hour. Value: 00-23
MM Minute. Value: 00-59
SS Second. Value: 00-59

The format of date is CYYMMDD, where:

C Century, where 0 indicates years 19xx and 1 indicates years 20xx.
YY Year. Value: 00-99
MM Month. Value: 01-12
DD Day. Value: 01-31

Text description. Text description of the change request description specified.

User profile to run under. Whether the authority checking done while this change request is running is based on the user who submitted the change request or the owner of the change request description. Possible values are:

*OWNER Change request runs under the user profile of the owner of the change request description.
*SBM Change request runs under the submitter of the change request.


Error Messages

The following messages are possible as either escape messages or return codes.

Message ID Error Message Text
CPF2150 E Object information function failed.
CPF2151 E Operation failed for &2 in &1 type *&3.
CPF24B4 E Severe error while addressing parameter list.
CPF3C19 E Error occurred with receiver variable specified.
CPF3C21 E Format name &1 is not valid.
CPF3C24 E Length of the receiver variable is not valid.
CPF3C90 E Literal value cannot be changed.
CPF3CF1 E Error code parameter not valid.
CPF8100 E All CPF81xx messages could be returned. xx is from 01 to FF.
CPF9693 E Activity &1 not found.
CPF9694 E Activity name required.
CPF969E E Internal processing error occurred.
CPF96A2 E CRQD library name &1 not valid.
CPF9801 E Object &2 in library &3 not found.
CPF9802 E Not authorized to object &2 in &3.
CPF9803 E Cannot allocate object &2 in library &3.
CPF9804 E Object &2 in library &3 damaged.
CPF9807 E One or more libraries in library list deleted.
CPF9808 E Cannot allocate one or more libraries on library list.
CPF9810 E Library &1 not found.
CPF9820 E Not authorized to use library &1.
CPF9830 E Cannot assign library &1.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V3R1

[ Back to top | Network Management APIs | APIs by category ]