233 lines
14 KiB
HTML
233 lines
14 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE html
|
||
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html lang="en-us" xml:lang="en-us">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="security" content="public" />
|
||
|
|
<meta name="Robots" content="index,follow" />
|
||
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
|
|
<meta name="DC.Type" content="concept" />
|
||
|
|
<meta name="DC.Title" content="API description" />
|
||
|
|
<meta name="abstract" content="For most APIs, the API description information has similar section headings." />
|
||
|
|
<meta name="description" content="For most APIs, the API description information has similar section headings." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="cmnCommon.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="cmnFieldRPG.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="cmnHoldRPG.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/qwdrjobd.htm#authority" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/qusljob.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="cmnDesc" />
|
||
|
|
<meta name="DC.Language" content="en-us" />
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
|
<title>API description</title>
|
||
|
|
</head>
|
||
|
|
<body id="cmnDesc"><a name="cmnDesc"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">API description</h1>
|
||
|
|
<div><p>For most APIs, the API description information has similar section
|
||
|
|
headings.</p>
|
||
|
|
<p>The following lists the API description section headings, each with an
|
||
|
|
overview and details on how to use the information.</p>
|
||
|
|
<p>For more information, see the following:</p>
|
||
|
|
<ul><li><a href="#cmnDesc__HDRPARAM">Parameters</a></li>
|
||
|
|
<li><a href="#cmnDesc__HDRAUTHLK">Authorities and locks</a></li>
|
||
|
|
<li><a href="#cmnDesc__HDRREQPARM">Required parameter group</a></li>
|
||
|
|
<li><a href="#cmnDesc__HDROPTPARM">Optional parameter group</a></li>
|
||
|
|
</ul>
|
||
|
|
<div class="section" id="cmnDesc__HDRPARAM"><a name="cmnDesc__HDRPARAM"><!-- --></a><h4 class="sectiontitle">Parameters</h4><p>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>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(<em>x</em>) represents <em>x</em> bytes
|
||
|
|
of a binary value. CHAR(<em>x</em>) represents <em>x</em> 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 <a href="#cmnDesc__HDRFORMN">Format name</a>.</p>
|
||
|
|
<p id="cmnDesc__HDRPARMEX"><a name="cmnDesc__HDRPARMEX"><!-- --></a><strong>Example:
|
||
|
|
RPG call statement parameters</strong></p>
|
||
|
|
<p>In this example program, you must
|
||
|
|
pass 5 parameters to use the API. For example, your RPG CALL statement might
|
||
|
|
look like the following:</p>
|
||
|
|
<pre> 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</pre>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> There is no parameter for the HOLD information. The first
|
||
|
|
parameter, receiver variable (QWDBH), is where the information is passed back
|
||
|
|
from the job description API. You will receive a data structure that contains
|
||
|
|
information, and you will need to find the specific location within the data
|
||
|
|
structure for where the HOLD information is stored.</div>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="cmnDesc__HDRAUTHLK"><a name="cmnDesc__HDRAUTHLK"><!-- --></a><h4 class="sectiontitle">Authorities and locks</h4><p>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:</p>
|
||
|
|
<ul><li>The API itself</li>
|
||
|
|
<li>All the objects that the API uses</li>
|
||
|
|
<li>Any locks that the API places on any objects</li>
|
||
|
|
</ul>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>To see the authorities in Retrieve Job Description Information
|
||
|
|
(QWDRJOBD) API, see the link to Authorities and locks in the Related reference
|
||
|
|
section.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="cmnDesc__HDRREQPARM"><a name="cmnDesc__HDRREQPARM"><!-- --></a><h4 class="sectiontitle">Required parameter group</h4><p>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.</p>
|
||
|
|
<p>The details of each parameter
|
||
|
|
that must be used on the call to the QWDRJOBD API are described in Required
|
||
|
|
parameter group.</p>
|
||
|
|
<p><strong>Receiver variable</strong></p>
|
||
|
|
<p>A receiver variable
|
||
|
|
is the name of the variable (QWDBH in the example RPG program in <a href="#cmnDesc__HDRPARAM">Parameters</a>)
|
||
|
|
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.</p>
|
||
|
|
<p>You can see from the <em>Dec</em> (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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p><strong>Length
|
||
|
|
of receiver variable</strong></p>
|
||
|
|
<p>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 <a href="#cmnDesc__HDRPARMEX">Example: RPG call statement parameters</a>,
|
||
|
|
RCVLEN is the length of receiver variable parameter.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p id="cmnDesc__HDRFORMN"><a name="cmnDesc__HDRFORMN"><!-- --></a><strong>Format
|
||
|
|
name</strong></p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p><strong>Qualified job description name</strong></p>
|
||
|
|
<p>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:</p>
|
||
|
|
<pre> 1 11 20
|
||
|
|
. . .
|
||
|
|
. . .
|
||
|
|
JOBD1 LIBX</pre>
|
||
|
|
<p>The special values of *CURLIB or *LIBL can be used as the library
|
||
|
|
qualifier.</p>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> APIs generally do not convert parameter values to uppercase.
|
||
|
|
When using object names (like job description and library), you must provide
|
||
|
|
the name in uppercase.</div>
|
||
|
|
<p><strong>Error code</strong></p>
|
||
|
|
<p>This parameter allows
|
||
|
|
you to select how errors are to be handled.</p>
|
||
|
|
<p>The include file QUSEC contains
|
||
|
|
the definition for the error code structure that is used for the error code
|
||
|
|
parameter.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="cmnDesc__HDROPTPARM"><a name="cmnDesc__HDROPTPARM"><!-- --></a><h4 class="sectiontitle">Optional parameter group</h4><p>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.</p>
|
||
|
|
<p>The
|
||
|
|
API can be called two ways: either with the optional parameters or without
|
||
|
|
the optional parameters.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="cmnCommon.htm" title="API names contain verbs that are similar to the i5/OS licensed program: change, create, remove, and retrieve.">API information format</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relref"><strong>Related reference</strong><br />
|
||
|
|
<div><a href="cmnFieldRPG.htm" title="This sample program shows the correct way of using the offset in a user space in RPG.">Example in OPM RPG: Accessing a field value (initial library list)</a></div>
|
||
|
|
<div><a href="cmnHoldRPG.htm" title="This example expects errors to be sent as escape messages.">Example in OPM RPG: Retrieving the HOLD parameter (exception message)</a></div>
|
||
|
|
<div><a href="../apis/qwdrjobd.htm#authority">Authorities and locks</a></div>
|
||
|
|
<div><a href="../apis/qusljob.htm">List Job (QUSLJOB) API</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|