The PADM (printer administration) call is used to administer the printers associated with an LTERM printer control.
PADM provides you with the following functions:
activate or deactivate confirmation mode for an LTERM printer control.
Unix, Linux and Windows systems
This function applies globally to the cluster in UTM cluster applications.confirm or repeat a printout
modify the assignment of a printer to an LTERM partner.
Unix, Linux and Windows systems
This function is not permitted in UTM cluster applications.modify the printer status, i.e. lock and release printer, set up or clear connection to a printer.
Unix, Linux and Windows systems
Locking and releasing apply globally to the cluster in UTM cluster applications.read information about a printer into the message area
read information about printouts to be confirmed.
Setting the KDCS parameter area (1st parameter)
The table below shows the various options and the necessary entries in the KDCS parameter area.
Function of the call | Entries in the KDCS parameter area | ||||||
|---|---|---|---|---|---|---|---|
KCOP | KCOM | KCLA | KCRN | KCLT | KCACT | KCADRLT | |
Confirm printout | "PADM" | "OK" | 0 | Control ID | LTERM name | Binary zero | Binary zero |
Repeat printout | "PADM" | "PR" | 0 | Control ID | LTERM name | Binary zero | Binary zero |
Change confirmation mode | "PADM" | "AT"/"AC" | 0 | Control ID / blanks | LTERM name | Binary zero | Binary zero |
Change printer assignment | "PADM" | "CA" | 0 | Control ID | LTERM name | Binary zero | LTERM name |
Change printer status | "PADM" | "CS" | 0 | Control ID | LTERM name | ON/OFF/CON/DIS | Binary zero |
Information on printout | "PADM" | "AI" | 44 | Control ID / blanks | LTERM name | Binary zero | Binary zero |
Information on printer | "PADM" | "PI" | 34 | Control ID / blanks | LTERM name | Binary zero | Binary zero |
You must set binary zero in all the fields not used in the KDCS parameter area
Setting the 2nd parameter
Here you supply the address of the message area to which openUTM is to read the message.
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"PADM" | |
"OK"/"PR"/"AT"/"AC"/"CA"/"CS"/"AI"/"PI" | |
Length in bytes / 0 | |
Control ID / blanks | |
LTERM name of control terminal | |
"ON"/"OFF"/"CON"/"DIS"/binary zero | |
Binary zero/ LTERM name | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_PADMOK/KDCS_PADMPR/KDCS_PADMAT/KDCS_PADMAC | (nb,kcrn,kclt) |
KDCS_PADMCA | (nb,kcrn,kclt,kcadrlt) |
KDCS_PADMCS | (nb,kcrn,kclt,kcact) |
KDCS_PADMAI/KDCS_PADMPI | (nb,kcla,kcrn,kclt) |
openUTM return information | |
|---|---|
Contents | |
Data/- | |
Field name in the KB return area | |
Actual length | |
Return code | |
Internal return code | |
Follow-up control ID/blanks | |
For the PDAM call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, the PADM operation code.
KCOM
In the KCOM field
OK: confirm printout
PR: repeat printout
AC: activate acknowledgement mode.
Unix, Linux and Windows systems
AC applies globally to the cluster in UTM cluster applications.AT: deactivate acknowledgement mode, i.e. switch back to automatic mode.
Unix, Linux and Windows systems
AT applies globally to the cluster in UTM cluster applications.CA: assignment to a different LTERM.
Unix, Linux and Windows systems
CA is not permitted in UTM cluster applications.CS: change the state of a printer.
Unix, Linux and Windows systems
CS for locking and releasing applies globally to the cluster in UTM cluster applications.AI: read information about printouts to be confirmed
PI: read information about printer
KCLA
In the KCLA field, the length of the data to be transferred to the message area.
if KCOM=AI: 44
if KCOM=PI: 34
and 0 for all other variants.
KCRN
In the KCRN field
for KCOM = OK/PR/CA/CS the control ID of a printer as generated in thePTERM statement with KDCDEF
for KCOM = AT/AC/AI/PI the control ID of a printer (as per PTERM statement) or blanks if the operation is to be valid for all printers assigned to the printer control terminal.
KCLT
In the KCLT field, the LTERM name of the LTERM printer control. If your own terminal is not the printer control terminal, your user ID must have administration privileges.
KCACT
In the KCACT field, if KCOM = CS the action to be performed:
ON: the printer is unlocked (STATUS = ON);
Unix, Linux and Windows systems
applies globally to the cluster in UTM cluster applications.OFF: the printer is locked (STATUS = OFF);
Unix, Linux and Windows systems
applies globally to the cluster in UTM cluster applications.CON: set up virtual connection to printer
DIS: clear virtual connection to printer.
Enter binary zero for all other variants.
KCADRLT
In the KCADRLT field with KCOM = CA, the name of the LTERM partner to which the printer is to be reassigned. The printer is identified by its control ID specified in KCRN.For all other variants binary zero is entered.
You specify the following for the KDCS call:
1st parameter
The address of the KDCS parameter area.
2nd parameter
The address of the message area to which UTM is to read the message. You enter the address of the message area even if you have entered the length 0 in KCLA.
Macro names
The use of C/C++ calls is described in detail in the section "C/C++ macro interface".
openUTM returns:
Message area
For KCOM = AI/PI: in the specified message area the message in its actual length but not exceeding the desired length.
KCRLM
In the KCRLM field, the actual length of the message which may differ from the length specified in KCLA of the parameter area.
KCRCCC
In the KCRCCC field, the KDCS return code, see next page.
KCRCDC
in the KCRCDC field, the internal return ode of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).
KCRMF/kcrfn
in the KCRMF/kcrfn field, if KCOM = AI/PI, the control ID of the next printer which is assigned to the printer control LTERM or blanks if it is the last assigned printer.
KDCS return codes in the KCRCCC field for the PADM call
The following codes can be analyzed in the program:
000 | Operation carried out (for KCOM = AI/PI) or the administration job is accepted (for KCOM = OK/PR/CA/CS/AT/AC). |
01Z | Length conflict: KCLA < KCRLM, the message is truncated. |
40Z | System cannot perform the operation (generation error or system error, no authorization for this call), see KCRCDC. Only on Unix, Linux and Windows systems: |
42Z | Entry in KCOM is invalid. |
43Z | Length entry in KCLA is negative or invalid. |
44Z | Control ID specified in KCRN is invalid or there is no printer with this control ID in the area of the control terminal. |
46Z | Entry in KCLT is invalid because no LTERM printer control has been defined for this name. |
47Z | Message area missing or cannot be accessed in the specified length. |
49Z | Contents of fields not used in the KDCS parameter area not equal to binary zero. |
55Z | Entry in KCACT is invalid. |
56Z | Entry in KCADRLT is invalid. |
An additional return code can be found in the dump:
71Z | INIT missing in this program. |
Return information in the message area for PADM AI
You can use a language-specific data structure to structure the message area when calling PADM AI. For COBOL this is defined in the KCPADC COPY element and for C/C++ in the kcpad.h include file. It has the following structure: No negative confirmation job
Byte | Field name | Meaning | |
|---|---|---|---|
1 - 8 | KCACKCID | Control ID of the printer | |
9 - 16 | KCGENUID | UTM user ID of the job originator | |
17 - 24 | KCDPUTID | Job ID (assigned by openUTM) | |
25 - 33 | KCGENTIM1 | Time of the FPUT/DPUT call in the form dddhhmmss: | |
25 - 27 | KCGENDOY | ddd | Day of the year (value range 001 - 366) |
28 - 29 | KCGENHR | hh | Hour (value range 00 - 23 |
30 - 31 | KCGENMIN | mm | Minute (value range 00 - 59) |
32 - 33 | KCGENSEC | ss | Second (value range 00 - 59) |
34 - 42 | KCSTTIM1 | For time-delayed jobs the required start time dddhhmmss: | |
34 - 36 | KCSTDOY | ddd | Day of the year (value range 001 - 366) |
37 - 38 | KCSTHR | hh | Hour (value range 00 - 23) |
39 - 40 | KCSTMIN | mm | Minute (value range 00 - 59) |
41 - 42 | KCSTSEC | ss | Second (value range 00 - 59) |
Blanks are entered for a job without time delay. | |||
43 | KCPOSMSG | Y | Positive confirmation job |
N | No positive confirmation job | ||
44 | KCNEGMSG | Y | Negative confirmation job |
N | No negative confirmation job | ||
1 For C/C++ the summary fields KCGENTIM and KCSTTIM are not defined. However, the specific fields for day/month/year/working day/hour/minute/second are defined.
If there is no printout to be confirmed, openUTM writes blanks in the message area.
Return information in the message area for PADM PI
You can use a language-specific data structure to structure the message area when calling PADM PI. For COBOL this is defined in the KCPADC COPY element and for C/C++ in the kcpad.h include file. It has the following structure:
Byte | Field name | Meaning |
|---|---|---|
1 - 8 | KCPRTCID | Control ID of the printer |
9 - 11 | KCSTATE | Status of the printer: ON or OFF |
12 | KCCON | Printer connection: |
13 - 14 | KCPRTMOD | Print mode: |
15 - 22 | KCLTRMNM | LTERM name of the assigned printer |
23 - 28 | KCFPMSGS | Number of output jobs for this printer (without number in KCDPMSGS) |
29 - 34 | KCDPMSGS | Number of time-driven jobs pending for this printer whose target time has not yet been reached. |
Features of the PADM call
PADM calls with the modification AT/AC are not executed until the end of the transaction. For the calls PADM OK/PR/CS/CA, a check is made only at the end of the transaction as to whether the call can be executed at all. Thus KCRCCC = 000 after such a call does not necessarily guarantee that the call can be successfully executed, because in the meantime there might be loss of connection to the printer, for example. You can issue a PADM AI or PADM PI call in a subsequent transaction to check whether a PADM OK/PR/CS/CA call has been successful.
If there is no printout to confirm for a PADM OK/PR call, then PADM OK or PADM PR provides the return code 40Z.
The printer assignment with PADM CA may only be changed if the two participating LTERMs are not connected with the application at call time, otherwise openUTM responds with 40Z.
When the printer is locked, openUTM responds with 40Z to reject a PADM CS call designed to set up a connection (KCACT = CON).