global: Operate on z/TPF global field

This function addresses (by indirection), updates, synchronizes, and keypoints global fields. It provides a high-level interface to z/TPF globals.

Note: z/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.

Last updated

Changed for PUT00.

Format

maketpf_env += system       
#include   <tpf/tpfglbl.h>  
#include   <tpf/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 as previously described, or code subsequent calls to global specifying the other actions described in the following text. 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 parameter must be issued before issuing GLOBAL_SYNC. If synchronization with acknowledgment is required, use the tpf_glob_sync_wait function.

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.
  • Use this function only with z/TPF format-1 globals. To keypoint or synchronize z/TPF format-2 globals, use the tpf_glWrite and tpf_glClose functions.

Examples

The following example locks, copies, and updates (including modification synchronization) global field _ns1ns, which can be synchronized. 
#include <tpf/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

See gentag5 user's guide for more information about the gentag5 utility program.

See z/TPF C functions overview for more information about z/TPF C/C++ language support.