To make the passing of parameters through the KDCS interface easier, macros are provided in the kcmac.h header file for each of the KDCS calls. These macros contain all the data specifications required for a KDCS call as macro parameters. These macros execute the desired call and then provide a return code (see also "Programming the KDCS error handling routines").
The names and characteristics of the various macros and how the macro names were created will be explained in the following section. The preparations you must make in order to utilize the kcmac.h header file are discussed. You will find an example of a macro call and a program listing of an executable KDCS program that will clarify the use of the kcmac.h header file at the end of the section.
Using KDCS_SET to prepare for a call
In each compilation unit in which you want to call a KDCS macro, you must execute the following two actions before the first macro call:
Copy the include file kcmac.h into the compilation unit
Copy the kcmac.h header file into the program unit
The four header files kcca.h, kcpa.h, kcapro.h and kcdf.h are used implicitly when kcmac.h is used, i.e. the definitions therein are available to the programmer at all times.
Call the KDCS_SET(pb,hdr,rti) macro for initialize the areas
pb: pointer to the KDCS parameter area.
hdr: pointer to the header area of the communication area (ca_hdr data structure).
rti: pointer to the return area of the communication area (ca_rti data structure).
The KDCS_SET call establishes the connection between the KDCS macros and the programmer’s definitions for the parameter area and the communication area. You can call this macro more than once. It is therefore possible to use several different parameter areas, for example.
Macro names
The names of the macros are created according to the following rules:
A KDCS macro name always begins with the prefix "KDCS_". The operation code of the desired KDCS call follows in upper case letters. If necessary, the operation modifier is appended to the operation code (also in uppercase letters).
Examples:
KDCS_INIT, KDCS_LPUT, KDCS_MGET
KDCS_MPUTNT, KDCS_PENDFI, KDCS_SPUTMS
The DPUT calls using a "+T", "-T", "+I" or "-I" as the kcom parameter represent an exception to these rules. These macros are named: KDCS_DPUTPT, KDCS_DPUTMT, KDCS_DPUTPI and KDCS_DPUTMI.
Other exceptions are the APRO calls used to address OSI TP partners:
KDCS_APRODM_OSI, KDCS_APROAM_OSI, KDCS_APRODM_OSI_O, KDCS_APROAM_OSI_O
Macro parameters
The macro parameters are each named after the KDCS parameters for which they will contain values (kcrn, kclt, kchour, kcpi,...). The KDCS message area is named nb and, if it is needed, is always specified as the first parameter.
There are three different types of KDCS parameters: character arrays, letters and numbers:
Character arrays
In the KDCS interface these parameters are either two, three or eight characters long. In the C/C++ macro interface these parameters are specified as pointers to a C string of any length.
Internally, these parameters are converted to arrays of characters of the required length by either appending any eventually missing spaces to the end of the C string or by ignoring all superfluous characters at the end of the C string. In this manner, for example, for an array of length 8, three spaces " " or no space "" are converted to the same string, namely eight spaces: " ".
A string such as "xyz" is filled up with five spaces to "xyz ". The conversion is performed without adding an end of string character ("\0").Parameters of this type are: kcrn, kcfn, kclt, kcpa, kcus, kcadrlt, kcact, kcpi, kcpos, kcneg, kccomid, kclangid, kcterrid, kccsname.
Letters
In the KDCS interface these parameters are of type character.
In the C/C++ macro interface these parameters are also specified as characters (per value). The parameters are specified in the form: ' ', 'A', 'C', etc.Parameters of this type are: kcmod, kcof.
Numbers
There are different types of numbers in the KDCS interface: short, unsigned short and numbers that are expected to be in the form of printable text.
In the C/C++ macro interface these parameters are always specified as numbers (per value). These numbers are converted internally to the desired format. Short and unsigned short numbers are passed directly. Numbers that must be provided as text are converted.Parameters of this type are: kcla, kclm, kcdf, kclcapa, kclspa, kcday, kchour, kcmin, kcsec, kcli.
Simplified parameter passing
The macros know the required length of every parameter and ensure that they are passed correctly (short strings are padded with spaces up to the required length). A parameter only needs to be specified in the macro parameter list and does not have to be passed anymore using memcpy. The macros also process all data that was previously processed with memcpy. The assignments of the parameters to the appropriate KDCS parameter fields is done implicitly by the C/C++ macros. The parameter types are determined by the C/C++ macro definitions.
For comparison, here is an example of supplying the kcrn parameter with data:
In a direct call:
memcpy(pb.kcrn,"rnam",8) /* only kcrn is supplied with data*/When using a macro:
macroname(...,"rnam",...) /* complete KDCS call*/
Any parameter fields not used are implicitly set to binary zero. You specify the constant KDCS_SPACES for the fields that are to be set to spaces in a call.
Some of the KDCS parameters that were previously passed as an array of characters are usually stored as integers in C.
Such parameters are, for example, the parameters used to specify the time and date: kcday, kchour, kcmin, kcsec. Such parameters are expected to be passed as numbers (integers) in the new macro calls. The macros ensure that the data is passed correctly to the interface.
Here is an example of supplying the KDCS call with a time specification for comparison:
In a direct call:
memcpy(pb.kcext.kcdput.kcday,"003",3); memcpy(pb.kcext.kcdput.kchour,"11",2); memcpy(pb.kcext.kcdput.kcmin,"55",2); memcpy(pb.kcext.kcdput.kcsec,"00",2);
When using a macros:
macroname(...,3,11,55,0)
Format of the KDCS call through the C/C++ macro interface
KDCS calls using the C/C++ macro interface have the following format:
KDCS_ operation_code [ operation_modifier ]( parameter_list )
If a KDCS message area is required, then its address is always specified as the first parameter. The parameter list can also be empty.
There are a few exceptions to the macro name format (see "C/C++ macro interface").
KDCS_INIT(length_communication_area_program_area,length_standard_primary_working_area); KDCS_SGETRL(pointer_to_message_area, message_length, name_of_local_secondary_storage_area) KDCS_PGWTKP()
Example: KDCS_MPUTNT macro call
In the following the use of a KDCS macro is demonstrated with an example of an MPUT NT call. First, a description of the macros:
KDCS_MPUT NT(nb,kclm,kcrn,kcfn,kcdf)
char *nb | pointer to the KDCS message area |
short kclm | length |
char kcrn[8] | space/TAC/service ID |
char kcfn[8] | format/space/edit profile |
unsigned short kcdf | screen fill character / binary zero / --- |
The KDCS_MPUTNT macro requires five parameters, one of which is a pointer to the KDCS message area nb. This parameter is always passed as the first parameter. The other parameters of the macro originate in the KDCS parameter area. The required type and meaning of each parameter is specified (for example, kclm is of type short and specifies the length of the area in which the message is to be passed). In the following example, NB is a pointer to the KDCS message area used and kc_pa is the KDCS parameter area.
A typical macro call looks like the following call, for example:
KDCS_MPUTNT(NB,10,KDCS_SPACES,KDCS_SPACES,KCNODF);
The same call without using a macro looks like (direct KDCS interface call):
memcpy(PB.kcop,MPUT,4); memcpy(PB.kcom,NT,2); kc_pa.kclm=10; memcpy(kc_pa.kcrn," ",8); memcpy(kc_pa.kcfn," ",8); kc_pa.kcdf=0; KDCS(&kc_pa,NB);
DEBUG function
You can enable a logging function during run time for the KDCS calls triggered by the macros. The calling module, the source code line and the KCOP, KCOM, KCRCCC and KCDCDC KDCS fields are recorded.
The logging function is switched on as follows:
Unix, Linux and Windows systems :
By setting and exporting the KDCS_C_DEBUG environment variable.
The information logged is written to stdout.BS2000 systems:
By setting the *KDCSCDB JOB VARIABLE LINK.
The information logged is written to SYSOUT.
Please note that the job variable link must point to a non-empty job variable.Example/CREATE-JV JV-NAME = KDCSCDB /MODIFY-JV JV-CONTENTS = KDCSCDB, SET-VALUE = 'YES' /SET-JV-LINK LINK-NAME = *KDCSCDB, JV-NAME = KDCSCDB
You will find additional information on this subject in the openUTM manual ”Messages, Debugging and Diagnostics”.
Note: Macros as statement follow-ups
The KDCS macros are not simply individual C/C++ functions, rather they are a series of several statements. The means that a single macro must be handled exactly as would be required for a series of several statements. This peculiarity is normally not relevant, and the macros can be used like normal C/C++ functions. There are, however, program structures that require single statements, for example within an if statement:
if (condition) STATEMENT else STATEMENT;
Because the macros consist of several individual statements, it is not possible simply to use a macro as if it were one (single) STATEMENT. You must therefore first designate the macro as a unified block. This is done by using curly brackets: {macro;}. Instead of incorrectly writing
you should write:
|
|