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 value 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 to the API could be lost on the return from the call to the API.

In the fourth column of the Parameters box is the type of data defined for the parameter. CHAR(*) represents a data type that is not known, such as character, binary, and so on, or a length that is not known. Binary(x) represents x bytes of a binary value. CHAR(x) represents x bytes of character data. When calling the QWDRJOBD API, for example, there is 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 made up of several character and binary fields. For more information on format names, see Format name.

Example: RPG call statement parameters

In this example program, you must pass 5 parameters to use the API. For example, your RPG CALL statement might look like the following:

     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

Authorities and locks

The Authorities and Locks topic lists all the authorities that you need to use the API. This topic also lists the locks that the API uses. To use an API, you must have the correct authority to the following:

• The API itself
• All the objects that the API uses
• 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.

To see the authorities in Retrieve Job Description Information (QWDRJOBD) API, see the link to Authorities and locks in the Related reference section.

Required parameter group

The Required parameter group topic of an API lists all the parameters required for that API. You must use all of the parameters in the order that they are listed. None of the parameters may be left out.

The details of each parameter that must be used on the call to the QWDRJOBD API are described in Required parameter group.

Receiver variable

A receiver variable is the name of the variable (QWDBH in the example RPG program in Parameters) where the information will be placed. 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 on 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 have a choice of receiving 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 could specify that the receiver variable is 100 bytes (or any number greater than or equal to 86 bytes). It is not necessary to be precise when you specify 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, specify more length than the format has, and so on.

For example, assume that you decided to receive the fixed information, a length of 390, 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 would usually use the length of the information that you want to receive. The length of 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 decided to declare the receiver variable to be 390 bytes in length. The length of receiver variable parameter will have 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 the example program in Example: RPG call statement parameters, RCVLEN is the length of 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. The API does not care if the field is declared as a binary type. For example, some languages, like control language (CL), do not have a binary type. What is important is that the field is 4 bytes in length and that it contains the receiver length in binary.

If you write programs in CL, you need the %BIN function to convert a decimal value or variable to a character field that is declared as 4 bytes. If you write programs in RPG, you can declare a data structure that contains a 4-byte field of zero decimals and is defined as B for binary, shown at (2) in Example in OPM RPG: Retrieving the HOLD parameter (exception message). Because the field is a binary type, RPG would make a binary value.

Format name

A format name is a name that identifies what type of information you want returned in the receiver variable. Because this API has a single format name, JOBD0100, you would use the format name given in the Retrieve Job Description Information API, 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, you would specify:

         1         11        20
         .          .         .
         .          .         .
         JOBD1      LIBX

The special values of *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 if an exception occurred. Depending on your high-level language, you may not have a choice for which method you use. You may have to use the error-code data structure because some languages do not provide for 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 for 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 sent.

Optional parameter group

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

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

The Retrieve Job Description Information API has no optional parameter groups. The List Job (QUSLJOB) API is an example of an API with an optional parameter group.