API description

Parameters

The Parameters box describes how to call the API.

The first column in the Parameters box lists the required order of the parameters.

The second column lists each parameter used on the call.

The third column lists whether the parameter is defined for input, output, or input and output. Input parameters and fields are not changed by the API. They have the same values on the return from the API call as they do before the API call. In contrast, output parameters are changed. Any information that an API caller places in an output parameter or output field before the call can be lost on the return from the call.

The fourth column of the Parameters box lists the type of data that is defined for the parameter. CHAR(*) represents a data type that is indeterminate, such as a data structure, or represents a data type of a length that is not fixed. Binary(x) represents x bytes of a binary value. CHAR(x) represents x bytes of character data. For example, the Retrieve Job Description Information (QWDRJOBD) API has parameters such as an 8-byte character format name, a 4-byte binary value named length of receiver variable, and a variable-length receiver variable. The receiver variable is a structure that consists of several character and binary fields. For more information about format names, see Format name.

Example: RPG call statement parameters

For the QWDRJOBD API, you must pass 5 parameters as shown in the following RPG CALL statement:

     C                     CALL 'QWDRJOBD'
     C                     PARM           QWDBH            Receiver Var.
     C                     PARM           RCVLEN           Length QWDBH
     C                     PARM           FORMAT           Format Name
     C                     PARM           LFNAM            Qual. Job Desc
     C                     PARM           QUSBN            Error Code

For complete RPG example programs that use the QWDRJOBD API, see Examples: Program-based APIs.

Authorities and locks

The Authorities and Locks section lists all the authorities that you need to use an API. This section also lists the locks that the API uses.

To use an API, you must have the correct authority to the API, to all the objects that the API uses, and to any locks that the API places on any objects.

Locks are based on the objects that the API uses. The type of locking that occurs, such as whether the object can be used by more than one user at the same time, is based on what actions the API performs on the object.

For the QWDRJOBD API, you must have *USE authority to both the job description object and the library to access the object. This is the same type of authority that is required for most situations where you want to display or retrieve information in an object. For example, it is the same authority that you would need to use the Display Job Description (DSPJOBD) command. Because no specific information is described for locks, you can assume that nothing unusual is required.

Required parameter group

The Required Parameter Group section lists all the parameters that are required for an API. You must use all of the parameters in the order that they are listed. None of the parameters can be left out.

The details about each parameter that must be used on the call to the QWDRJOBD API are described in the Required Parameter Group section in Retrieve Job Description Information (QWDRJOBD) API.

Receiver variable

A receiver variable is the name of the variable where the retrieved information is placed, for example, QWDBH in the example RPG program in Parameters.

You need to declare the length of the receiver variable based on what you want from the format. The include file QWDRJOBD contains the definition for the receiver variable structure depending on the value used for the format name. For more information about the format, see the table in JOBD0100 Format.

You can see from the Dec (decimal offset) column of the JOBD0100 format table that at least 390 bytes plus additional bytes (of unknown length) for the initial library list and the request data are returned. Example in OPM RPG: Accessing a field value (initial library list) describes how to determine the lengths of these fields. For now, you should focus on the fixed portion (390 bytes) of the format.

You can receive the maximum or enough bytes to contain the information in which you are interested. Because the value of the hold on job queue field starts at decimal 76, you can specify that the receiver variable is 100 bytes in length (or any number greater than or equal to 86 bytes). You do not need to be precise about the length of the receiver variable. Whatever you specify is the amount of data that is returned. You can truncate a value in the middle of a field in the format or specify more length than the format has.

Assume that you want to receive the fixed information, a length of 390 bytes, shown at (1) in Example in OPM RPG: Retrieving the HOLD parameter (exception message). If you are going to call the API once, no measurable performance gain occurs if you specify anything less than the maximum. When defining the length of your receiver variable, you usually use the length of the information that you want to receive. The length of the receiver variable parameter must be set to a value equal to or less than the length that you defined the receiver variable parameter to be.

Length of receiver variable

You normally enter the length that you have specified for the receiver variable. Remember that in this example, you want to declare the receiver variable to be 390 bytes in length. The length of the receiver variable parameter has a value of 390 assigned to it, shown at (2) in Example in OPM RPG: Retrieving the HOLD parameter (exception message). You could have specified a different value, but the value must be the same or less than the size of the variable in your program. In Example: RPG call statement parameters, RCVLEN is the length of the receiver variable parameter.

The length field, according to the required parameter group, must be described as BINARY(4). This means that a field of 4 bytes is passed where the value is specified in binary. You need to know how your high-level language allows you to define a 4-byte field and place a binary value in it.

Format name

A format name is a name that identifies what type of information you want returned in the receiver variable. Because the QWDRJOBD API has a single format name, JOBD0100, you use this format name shown at (3) in Example in OPM RPG: Retrieving the HOLD parameter (exception message). The format name variable in the example program is called FORMAT. You can place the format name in a variable or pass it as a literal.

Qualified job description name

This name must be passed as a 20-character name with the job description name in the first 10 characters and the library qualifier beginning in the 11th character. If you want JOBD1 in LIBX, specify as follows:

         1         11        20
         .          .         .
         .          .         .
         JOBD1      LIBX

The special value *CURLIB or *LIBL can be used as the library qualifier.

Error code

This parameter allows you to select how errors are to be handled.

The include file QUSEC contains the definition for the error code structure that is used for the error code parameter.

You can choose to receive exceptions (escape messages) or to receive an error-code data structure that allows you to determine whether an exception occurs. Depending on your high-level language, you might not have a choice for which method you use. You might have to use the error-code data structure because some languages do not provide for the monitoring of escape messages.

In Example in OPM RPG: Retrieving the HOLD parameter (exception message), the RPG program requests that exceptions be sent if any errors occur. To provide this type of exception handling, a 4-byte binary field with a value of zero must be passed, as shown at (4). This indicates to the API that you want exception messages to be sent.

Optional parameter group

Some APIs have optional parameters. The optional parameters form a group. You must either include or exclude the entire group. You cannot use only one of these parameters. You must include all preceding parameters.

The API can be called either with or without the optional parameters.

The Retrieve Job Description Information (QWDRJOBD) API does not have an optional parameter group. The List Job (QUSLJOB) API has an optional parameter group.