gtpc2m4aC/C++ Language Support User's Guide

global-Operate on TPF Global Field

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

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.