To handle situations in which your Datacom names do not match the MAGEC standard, you must define the Keys and Elements (cont.)
using the MAGEC standard names, but specify the true Datacom names in special fields within the MAGEC (cont.)
definitions.
If you have specified Datacom as the access method for a Data Class, there will appear on your KYFxxx screen and ELTxxx (cont.)
screen, special entry fields in which you can enter the true Datacom names. If you leave any of these entries blank, (cont.)
MAGEC assumes that the Datacom name is the same as the MAGEC name. These special entry fields have a prompt such as "CA (cont.)
DD Name".
Database ID's
Datacom DB permits you to define up to 999 Databases identified by 3-digit Database ID numbers. It also allows you to (cont.)
define tables with the same names in several Database numbers. For instance, you might have a CUS table in Database (cont.)
#101 and another CUS table in Database #367, et cetera.
The MAGEC DCLxxx definition provides for you to specify a test Database number and a production database number for (cont.)
each Data Class. If you do so, MAGEC's I/O module will automatically insert the appropriate Database ID into the I/O (cont.)
request based upon whether you are a test user or a production user (according to the User View you used to access (cont.)
MAGEC).
If you set the test and/or production Database number to 000 on the DCLxxx definition for a Data Class having the (cont.)
access method of Datacom, MAGEC's I/O module will not insert any Database number; rather, it will expect your (cont.)
application program to have set it (in TWA-DB-ID) as needed.
Datacom DB I/O accesses only require the Database ID to be set if SYNONYM=YES is specified in the User Requirement (cont.)
Table (URT) enabling your program to access more than one table of the same name. If not, Datacom will ingore the (cont.)
Database ID.
# Appendix E -- MAGECSET
Setting addresses into pointers
There are numerous occasions when a programmer must load the address of some area of memeory into a pointer. One (cont.)
example of such occasion is when calling MAGEC's I/O module, refer to examples shown in "Sample Code" earlier in this (cont.)
*Database Administration* section.
If you are using Cobol II, or Cobol/370, or any other ANSI 85 standard Cobol compiler, you can set addresses into pointers using the SET verb, as:
SET MY-POINTER TO ADDRESS OF MY-DATA.
In this example, the data item named MY-POINTER must be defined as USAGE IS POINTER, though it may be redefined as PIC (cont.)
X(4) or PIC 9(9) COMP if necessary. The address of the data item named MY-DATA will be set into the 4-byte field named (cont.)
MY-POINTER.
Since not all MAGEC users are using ANSI 85 Cobol compilers, MAGEC provides a subroutine to accomplish the identical (cont.)
results as the SET statement shown above. The subroutine is named "MAGECSET", and it is used as (cont.)
follows:
CALL "MAGECSET" USING MY-POINTER MY-DATA.
In this case it does not matter whether MY-POINTER is defined as PIC X(4), PIC S9(9) COMP, or any other format. (cont.)
MAGECSET assumes that MY-POINTER is 4 bytes long and sets the address of MY-DATA into it. The above statement will work (cont.)
identically whether you are using Cobol II, Cobol/370, VS Cobol (ANSI 74), or any other Cobol compiler. It works on the (cont.)
mainframe, PC, or Unix systems identically. It is therefore more portable than the Cobol SET verb.
# Appendix F -- Read-Ahead
TWA-DB-RETURN-CODE
The primary use for the field named TWA-DB-RETURN-CODE in the request area passed to MAGECIO is for the I/O module to (cont.)
pass a return code back to your program indicating the success or failure of your request. However, it is also possible (cont.)
for your program to pass commands to MAGECIO using TWA-DB-RETURN-CODE. One of the commands you can pass here is "RQ", (cont.)
indicating that you would like the I/O module to queue records for you since you intend to do a number of sequential (cont.)
reads (REDNX, REDPR, or REDBR commands).
If you are accessing a file that is local to you (not accessed via a Gateway), this command will be ignored by MAGECIO. (cont.)
If you are accessing a file that is remote using MAGEC's intrinsic TCP/IP networking capabilities, then MAGECIO will (cont.)
attempt to build a queue of records at the host machine and pass them as a block to the local I/O module. As your (cont.)
program requests subsequent read-nex or read-previous commands MAGECIO will satisfy them from the buffer of queued (cont.)
records until that buffer-load of records is expired, then will request another block of records from the Gateway (cont.)
machine. This reduces the number of messages transmitted between the client and host machines, and can also enhance the (cont.)
benefits of MAGEC's built-in compression of those transmissions.
Read-Ahead processing can greatly improve performance for sequential processing agains a remote file; however, its (cont.)
mis-use can impose a performance penalty. It is best to understand how read-ahead processing works in order to ensure (cont.)
optimum performance.
When your application program calls MAGECIO to access a remote file, MAGECIO in turn calls MGCLIENT. MGCLIENT formats a (cont.)
Remote I/O Command message and sends it to the appropriate Gateway (using the IP address defined for that Gateway in (cont.)
MAGEC Table #248). The message is received by the MAGEC Host program (we will assume a name of "MGHOST") which calls (cont.)
the MAGECIO module at its location to access the requested data. MAGECIO (at the remote site) returns the data to (cont.)
MGHOST which formats a Remote I/O Response message and then sends it back to the requesting MGCLIENT in your computer. (cont.)
MGCLIENT formats the data returned into your TWA and returns control back to your local MAGECIO, which returns control (cont.)
back to your program. All transmissions are compressed for improved performance.
The MGHOST running at the remote site checks whether you have set the "RQ" command into TWA-DB-RETURN-CODE, and are (cont.)
also doing one of the sequential read comamnds: REDNX, REDPR, or REDBR. If so, MGHOST will attempt to read several (cont.)
records and build a queue of records to send back to MGCLIENT, rather than sending only one record back. The number of (cont.)
records it will queue up is limited to either 16 records, or 16 KBytes of data, whichever is less.
MGCLIENT receives this transmission containing a record queue and formats the TWA using the first record from the (cont.)
queue. It holds the entire queue of records in memory, in the area into which it was received, anticipating that your (cont.)
program's next request will be for the next record from the queue. For these purposes, reqeusts to files that are not (cont.)
remote do not count; therefore, your program may read several local files in between doing REDNX's (or REDPR's, or (cont.)
REDBR's) against the remote file. If the next request is the anticipated command, MGCLIENT will simply format the TWA (cont.)
with the next record from the queue, eliminating all overhead associated with the two-way communication with MGHOST. If (cont.)
the next command is not the anticipated command, MGCLIENT will destroy the queue of records and satisfy the request by (cont.)
sending a message to MGHOST, as it normally does.
This means that any unused records in the queue are wasted. If your program then issues the next read-next request for (cont.)
the first file, it will have to be satisfied using the normal two-way communication.
As you can see, improper use of read-ahead can cause your application to do unnecessarily large transmissions and (cont.)
wasted I/O at the host site. Used properly it can greatly reduce both the number of messages sent over the network and (cont.)
the number of bytes sent (compression is more effective for the larger blocks).
It should be noted that for the read-ahead processing to work it is necessary that the TWA-DB-REQUEST area and the (cont.)
TWA-KEY-VALUE area be undisturbed from one request to the next. MAGECIO stores positioning information within these (cont.)
areas and checks for it on subsequent requests. If they have been altered MGCLIENT assumes that it cannot satisfy the (cont.)
request from its record queue and must pass the request on to MGHOST for processing. For this reason, your program (cont.)
should save both these areas after returning from MAGECIO, and restore them before the next request. This allows you to (cont.)
access other files in between. The default logic generated into your programs does the proper saving and restoring for (cont.)
your primary data class' data. The only exception to this is that the TWA-DB-RETURN-CODE will be returned to your (cont.)
program with the proper value to indicate the success of your request (usually spaces) and you will be (re)setting it (cont.)
to "RQ" prior to each call to MAGECIO.
Also refer to the Networks section of your *Application User's Guide* .
# Appendix G -- File Opens & Closes
## Implicit vs. Explicit Opens
When your programs access files using MAGECIO, whether in batch or online environemnts, they need never explicitly open (cont.)
the files unless they require a particular type of open different from the default which MAGECIO will use. For online (cont.)
program operating on a mainframe using CICS, your programs never issue explicit open commands and, if they do, the (cont.)
commands are ignored by MAGECIO and treated as a "no operation", exactly like the NOOPS command. For other (cont.)
environments. explicit open commands are honored, but if your program accesses a file using another command, such as a (cont.)
REDKY, prior to opening the file, an implicit open is automatically issued. SInce the file is then open, you must issue (cont.)
a close to the file before you can successfully re-open it differently. Therefore, it is usually easiest to issue your (cont.)
explicit open commands prior to your first file access to ensure that the file is opened properly.
The implicit open is done in all environments unless you explicitly issue an open command; however, in the CICS (cont.)
environment file open and close capabilities are restricted by the CICS DFHFCT parameters. Files used by MAGEC are (cont.)
normally defined to CICS to be either opened initially as CICS is started up, or enabled to open as they are accessed. (cont.)
In online programs in any environment, it is unusual for you to ever issue any open commands. Most online programs (cont.)
simply use the implicit opens. If you do need to issue explicit opens in online programs, remember that each (cont.)
transaction constitutes a complete process and all files are closed as the screen is sent back to the operator. If you (cont.)
need to use an explicit open, it will have to be repeated for every transaction, e.g. do the open command in the (cont.)
%PREINIT insertion point.
## Default Opens
When your batch programs access files and invoke the implicit opens, a default open type is used by MAGECIO. The (cont.)
default open type is OPENU (open for input-output). This default open type is set when your program is initiated. You (cont.)
can alter the setting of the default open type, if you wish. If you alter the setting, the new setting will apply to (cont.)
any files open after you have altered it. Files opened prior to your changing the setting will have been opened using (cont.)
the old setting.
The *READ command can be issued at any time to change the default open type to OPENR (open for read-only). If your (cont.)
program is a report program which never needs to update any records on any files, you should issue the *READ command (cont.)
near the top of your processing logic so that all files will be opened read-only.
The *LOAD command can be used to reset the default open type to OPENU. Your program can issue the *LOAD and *READ commands any number of times throughout its processing.
Please note that these commands affect *only implicit* opens. Also note that explicit opens neither affect the default setting nor are affected by it.
## Explicit Opens
Several commands are provided for your programs to explicitly open a file. In the CICS environment all of these are ignored and treated as a NOOPS (no operation).
The OPENR command will open a file for read-only.
The OPENU command will open a file for input-output, allowing updates.
The OPENO command will open a file for output, intiializing the file.
The OPENE command will open a file "extended". This is valid only for a sequential file and allows you to add records to the "end" of the file.
The OPENX command will open a file for exclusive input-output. That means that no other user on the network will be (cont.)
able to access that file until you have closed it or reached end-of-job. This command has meaning only on a LAN/WAN and (cont.)
is equivalent to OPENU if issued on a mainframe. Opening exclusively will greatly speed your processing sicne not (cont.)
sharing logic will be executed.
## Explicit Closes
When an online program completes a transaction, sneding the screen to the operator, an implicit close is done (except (cont.)
in CICS) on all files that were left open. They will automatically be reopened with any positioning restored for the (cont.)
next transaction if needed. Explicit closes can be done prior to the end of your transaction, if you wish, to minimize (cont.)
resource consumption.
Batch programs also have their files closed implicitly at end-of-job. You can issue explicit closes to enable reopening (cont.)
the file differently. For example, if you have created a new file by opening for output, you may want to close it and (cont.)
reopen it using OPENU to be able to access and update records on that file.
The *CLSE command will close all files that are open and will issue a COMMIT to ensure that all data is flushed from file buffers and saved to disk.
The CLSFL, or CLOSE (they are synonyms) commands will close an individual file.
# Appendix H -- Sequential Files
To define a sequential file to MAGEC, use the access method SEQDS, SEQCMPR, OR SEQCRLF on the DCL definition. SEQDS (cont.)
specifies a fixed-length, non-compressed file. SEQCMPR specifies a compressed sequential file using the intrinsic (cont.)
compression facilities of the environments file systems (usually, MicroFocus Cobol). SEQCRLF specifies a sequential (cont.)
text file using Carriage Return-Line Feed ASCII characters to denote end-of-record.
Sequential files can be accessed using MAGECIO, however only certain commands can be issued against them. Obviously, (cont.)
without an index many of the facilities available to VSAM or other indexed access methods cannot be (cont.)
provided.
All of the explicit open commands are supported for sequential files, including OPENE, but excluding OPENI.
All of the close commands are supported.
The only read command supported is REDNX, which, for a sequential file requires no prerequisite except for an open.
The ADDIT command is used to write to a sequential file.The file must have been opened using OPENE.
The UPDAT command is used to rewrite a record to a sequential file.
If you issue a database command that is not supported for sequential files, though it is a valid command for other file types, you will be issued a return code of '1S' in TWA-DB-RETURN-CODE.
## Generic File Names
MAGEC in the PC environment allows you to define and access files using generic names. A generic name is one which (cont.)
includes one or more (maximum 7) question marks as the trailing characters of the file name. For example: (cont.)
FILE???.TXT.
At the time that your program first accesses the file using either an explicit or implicit open (REDNX, OPENR, or (cont.)
OPENX) MAGEC's IO module will access the directory of the PC file system (may be either a LAN or local file) to (cont.)
determine whether there are any files whose names match the generic name given, and which file name to use. In the case (cont.)
of an input file that means that there may be several files with matching names, e.g.: FILE001.TXT, FILE002.TXT, (cont.)
FILE003.TXT, etc.
The IO module will access the directory and will open the first (lowest in collating sequence) file. In this example (cont.)
FILE001.TXT. When you program reads to the physical end of FILE001.TXT, the IO module will again access the directory (cont.)
to obtain the next lowest file name and will open it as if it were concatenated to the first file, and so (cont.)
forth.
In order to avoid conflicts, the IO module renames the input file using an extension of "_IN" before opening it, and (cont.)
renames it using another extension immediately after it is closed. The extension used for this final rename operation (cont.)
is taken from the KYF description in the "Extension after file is processed" specification. The extension given here (cont.)
should not be the same as the original extension and should not be "_IN". For example, a good choice for Extension (cont.)
after file is processed would be "DUN" (for "done").
As you can see, using this scheme would mean that the IO module would first find FILE001.TXT, rename it to FILE001._IN, (cont.)
and open it for your program. When you have read through that file, it would rename it as FILE001.DUN and re-access the (cont.)
directory to find the new lowest file name matching the FILE???.TXT generic name. That would probably be ("probably" (cont.)
because of the possibility for multiple workstations to be performing the same process as discussed below) FILE002.TXT. (cont.)
Your program will read through several concatenated files as if they were one.
## Multiple Concurrent Processing
Using this scheme it is possible for several (unlimited number) of workstations attached to a server to concurrently (cont.)
process a "pool" of transaction files. The same program could be executing on each workstation processing the (cont.)
transactions against the same database or master files. Since the files are renamed before and after processing, other (cont.)
workstations will not recognize them as input files. Therefore, one workstation might process FILE001.TXT, then another (cont.)
might begin processing FILE002.TXT. When the first reaches the physical end of FILE001 it will automatically begin (cont.)
processing FILE003.TXT.
## Generic Output Files
In the case of generic file names for output files, the IO module will access the directory to determine the highest (cont.)
file name which currently exists matching the generic name. It will add one to the numeric (generic) portion of the (cont.)
file name and will open it for output using a temporary extension of "_OT". When your program closes the file the IO (cont.)
module renames it using the extension specified in the File specification, *not* the "Extension after file is (cont.)
processed"!
Multiple workstations could be creating files using the generic name and each will automatically use a unique name. (cont.)
They would likely be creating a pool of transaction files which will later be accessed as described (cont.)
above.
If you wish to write files using generic names your program must issue an explicit OPENO and an explicit CLOSE command.
## Generic Name Formats
Only sequential files may be specified using generic file names. Indexed files may not. Sequential files are defined using the access methods: SEQDS, SEQCMPR, or SEQCRLF on the DCL definition.
A generic name is any name including question mark characters (?) as the last characters of the name (not the (cont.)
extension). The question marks must be contiguous and may not be followed by any other character, except for the dot (cont.)
(.) which separates the name from the extension. There may be from one to seven question marks. The actual file names (cont.)
represented by the generic name must have numeric characters (1 - 9) in the positions held by the question marks. For (cont.)
example:

Next: <a href="https://magec.com/DOC/markdown/db14.md.txt">https://magec.com/DOC/markdown/db14.md.txt</a>