gtpc2m4a | C/C++ Language Support User's Guide |
This function addresses (by indirection), updates, synchronizes, and
keypoints global fields. It provides a high-level interface to TPF
globals.
- Note:
- TPF development uses the following convention for globals. The
@ symbol, used in assembler to begin all global field and record names,
is not permitted in any C identifier. Use an underscore symbol (_) in
its place. All remaining characters in the global tag name are
converted to lowercase. For more information about globals, refer to Appendix F, GNTAGH User's Guide.
Format
#include <tpfglbl.h>
#include <c$globz.h>
void *global(unsigned int tagname, enum t_glbl action, void *pointer);
- tagname
- This argument is treated as an unsigned integer that uniquely identifies
the global field to be operated on, which must be defined in header file
c$globz.h.
- action
- The action to be performed against tagname. Use one of
these defined terms:
- GLOBAL_UPDATE
- Update the specified global field with the value specified by the argument
pointer, whose length is determined by the defined length implicit
in the tagname definition. All functions requested to be
performed against the field (keypointing, processor synchronization, and
others) are validated based on the definition of the tagname. If the
field can be synchronized, a GLOBAL_LOCK must be issued before
GLOBAL_UPDATE. For this subfunction, argument
pointer is required. The GLOBAL_UPDATE action
will implicitly do a GLOBAL_UNLOCK action; you do not need to
explicitly issue GLOBAL_UNLOCK.
- GLOBAL_MODIFY
- Alter the specified global field with the value specified by the argument
pointer, whose length is determined by the defined length implicit
in the tagname definition. No additional functions are
performed against the field (keypointing, processor synchronization, and
others). To perform additional functions, you must either use the
GLOBAL_UPDATE action described above, or code subsequent calls to
global specifying the other actions described below. If the
field can be synchronized, a GLOBAL_LOCK must be issued before
using GLOBAL_MODIFY. For this subfunction, argument
pointer is required.
- GLOBAL_KEYPOINT
- Causes the keypointing of the specified global field. For this
subfunction, argument pointer is not required.
- GLOBAL_LOCK
- Reserves the exclusive use of the specified global field and forces
refreshing of the core copy from the most current file copy. The
contents of the specified global field are copied to user storage (pointed to
by argument pointer) for the defined length of the global
field. For this subfunction, argument pointer is
required. You should ensure that a lock is held for the shortest
possible time because severe system degradation may result from other ECBs
waiting for locks. This action is valid only for synchronizable
fields.
- GLOBAL_UNLOCK
- Inverse of GLOBAL_LOCK, which was explained previously.
Releases exclusive use of the specified global field. For this
subfunction, argument pointer is not required. You do not
need to issue GLOBAL_UNLOCK after a GLOBAL_UPDATE action
because GLOBAL_UPDATE implicitly does a
GLOBAL_UNLOCK.
A GLOBAL_LOCK must be issued before issuing
GLOBAL_UNLOCK. This action is valid only for synchronizable
fields.
- GLOBAL_COPY
- Copies the contents of the specified global field to user storage (pointed
to by argument pointer) for the defined length of the global
field. For this subfunction, argument pointer is
required.
- GLOBAL_SYNC
- Same as GLOBAL_UNLOCK as described previously, except that
synchronization of globals across processors in a loosely coupled complex is
performed. For this subfunction, argument pointer is not
required.
A GLOBAL_LOCK must be issued before issuing
GLOBAL_SYNC
- pointer
- This argument is optional (unless you specify GLOBAL_UPDATE,
GLOBAL_MODIFY, GLOBAL_LOCK, or GLOBAL_COPY),
and is treated as a pointer to type void. Its context
depends on the content of argument action as described previously,
and may be considered either a source or destination of field content.
Normal Return
Void.
Error Return
Not applicable.
Programming Considerations
- The argument coded as tagname must be defined in header file
c$globz.h. Results will be unpredictable if this
restriction is not heeded.
- Only operations against global fields are supported; global records
cannot be operated on. If the global tagname indicates that the
specified global field is a record and not a field, a system error with exit
results.
- Programs using the GLOBAL_LOCK option should be prepared to
issue a GLOBAL_UNLOCK as soon as possible to prevent severe system
degradation caused by the possibility of other ECBs awaiting locks on the
target global block.
- Programs using the GLOBAL_LOCK, GLOBAL_UNLOCK, or
GLOBAL_SYNC options should not have any pending I/O operations
outstanding because these functions may perform the equivalent of a
waitc function.
- A program should not give up control (by calling an I/O function, such as
finwc) between reading and updating a global field. If it
does, the data that the program reads may have already been updated by another
program by the time the program decides to update it. Use of the
locking facility provides additional security when updating synchronizable
global fields.
Examples
The following example locks, copies, and updates (including modification
synchronization) global field _ns1ns, which can be synchronized.
#include <tpfglbl.h>
int ns1ns;
·
·
·
global(_ns1ns, GLOBAL_LOCK, &ns1ns); /* Lock and get copy of */
/* synchronizable global */
ns1ns = ns1ns+1 /* Update value.
global(_ns1ns, GLOBAL_UPDATE, &ns1ns); /* Issue UPDATE. */
·
·
·
- Note:
- In the example given, _ns1ns is assumed to be synchronizable. If the
field is keypointable, issue GLOBAL_COPY instead of
GLOBAL_LOCK before the GLOBAL_UPDATE.
Related Information
glob-Address TPF Global Field or Record.