In addition to filling in the fields of the reqeust block as described in the Remote Execution topic, you must fill in (cont.)<br />all of the fields shown above. This request is used to execute an MMP on a CICS mainframe platform. The MMP you execute (cont.)<br />can be any normal MMP, with the following restrictions<br />Must not depend on screen input from an operator to execute<br />All FTHFUNCT, FTHMMP, and Attach commands will be ignored.<br />No response or return code will be sent back to the requesting program.<br />The requesting program will issue the request and immediately continue processing without waiting for initiation of the sub task.<br />The RXQT-TRNSID should be set to a valid MAGEC User-View such as: TS01, PR02, etc.<br />The RXQT-SFUNCT should be set to the MAGEC Function Code you wish to invoke (all uppercase), such as: CUSUPD, MSKCRE, etc.<br />The RXQT-SKEY should be set to the screen key value you wish to pass to the MMP.<br />The RXQT-AID should be set to the AID code to indicate a Function key, or Enter key hit.<br />The RXQT-DATE and RXQT-TIME fields should be set to the date and time in the exact format as they are found in TWA-IPL-DATE-CC and TWA-TIME.<br />The RXQT-INITIALS and RXQT-EMP-NO should be set to the operator's initials and employee number you wish to have set into the TWA to identify the requestor.<br />Note that the data being passed is used to build values into the TWA before invoking the requested function. MAGEC will (cont.)<br />access the FCD file to determine the actual MMP number to execute to proecess the specified function code, just as it (cont.)<br />would if the function code were entered into a screen in MAGEC online. Thus, the function code must be a valid code (cont.)<br />defined on the target (Host) machine.<br />The MMP will be executed via the standard EXEC CICS LINK just as if it had been invoked by the MAGEC control program in (cont.)<br />response to an operator entry at a 3270 terminal. It will not "know" that is was invoked in response to a remote (cont.)<br />request and that there is not actually a 3270 terminal to which it can send messages. If the MMP builds a screen (cont.)<br />messageand then exits to (it thinks) the control program to have the message sent to the (non-existent) terminal, no (cont.)<br />message will be sent and the task will simply end as if all processing were complete.<br />If you wish to code the mainframe MMP so that it can sense having been executed by a remote requestor, you can do so in several ways.<br />First, you might use a special function code which is never entered by a 3270 terminal operator, but which is only used (cont.)<br />for remote execution. The program could sense that function code and act accordingly.<br />Second, you could set a pseudo-AID code into the RXQT-AID field and test for it in your MMP. Be sure you do not use one (cont.)<br />which conflicts with any valid key code or low-values or high-values or "V" (which is used by the VERZUN function of (cont.)<br />MAGEC).<br />Third, your MMP could test for the special terminal ID or "#TCP" in TWA-TERMINAL-ID. This pseudo-terminal-ID is set by the remote execution requestor for all such executions.<br />Passing Data**<br />It might often be necessary to pass data to the mainframe sub-task from your PC-based requesting program. To do so you (cont.)<br />might be able to place it into the RXQT-SKEY field, which is 31 bytes long. If that is insufficient, you could pass a (cont.)<br />key value into the 31-byte field and place the larger data into a record on a file on the target mainframe system. The (cont.)<br />MMP could then read that record and retrieve a virtually unlimited amount of passed data.<br />Likewise, you could pass data back to the requestor from the sub-task by writing it to a record using the key value (cont.)<br />specified. The PC-based requestor could interrogate the record to retrieve the passed data.<br />**Wait for Completion**<br />Assuming that the requesting program and the sub-task program agree upon the format of the file record discussed above, (cont.)<br />one of the fields in that record could be a status code in which the sub-task will place a value to indicate successful (cont.)<br />completion or unsuccessful completion. The requestor could enter into a loop reading that record until it senses either (cont.)<br />of those values and then act accordingly.<br />When using this technique it is best to avoid monopolizing system resources by including code in your loop to delay and (cont.)<br />to yield dispatch priority to other tasks. Refer to the *Micro Focus Cobol* manuals for discussions of "PC_WIN_YIELD" (cont.)<br />and related topics. One technique for doing this is to perform a routine n-number of times which calls PC_WIN_YIELD as (cont.)<br />well as other time-delaying logic in between reading the status record.<br />If you add an additional status code value to indicate "processing", as well as completions, your requesting program (cont.)<br />could sense that its request is indeed being handled on the Host machine. It could display a progress report at the PC (cont.)<br />screen, if desired.<br />**ASCII / EBCDIC**<br />If your requestor program issues its request from an ASCII machine (which is most likely), and the Host is an EBCDIC (cont.)<br />machine, MAGEC will sense that and will translate the entire request into EBCDIC before sending it on to the Host. (cont.)<br />Since binary and packed data do not survive such a translation, and MAGEC would not know if you were to embed binary or (cont.)<br />packed data into, say, the SKEY field, you should set only text characters into the entire request block. The only (cont.)<br />exception is the RXQT-NR-OF-BYTES field, which is binary and is known to MAGEC therefore will be handled properly. In (cont.)<br />MAGEC 3.0 the value of this field is unconditionally set to +178 by MAGEC regardless what your program sets it (cont.)<br />to.<br />## <br />Variable Gateway Names<br />In a complex network which includes several servers, it may sometimes become useful for an application to have the (cont.)<br />ability to dynamically access identical files on any of several servers. For example, a network might consist of one (cont.)<br />MVS mainframe server, and one VSE mainframe server, plus a Windows NT server, and a Novell server. There could be a (cont.)<br />customer file on each of these servers, all having identical definitions, but possibly different sets of customer (cont.)<br />records on each (with, or without overlaps occurring). An application might wish to access the MVS customer file at one (cont.)<br />time, then later, access the Windows NT customer file, et cetera.<br />To accomplish this MAGEC has provided a special generic gateway name of "VARIABLE" which can be specified on the DCL (cont.)<br />definition for the [customer] file, and a special I/O module command which can be issued by an application program to (cont.)<br />stipulate the actual gateway name to be substituted for the word "VARIABLE" when it appears as the gateway (cont.)<br />name.<br />Therefore, the application might issue the special command as:<br />MOVE "SETVG" TO TWA_DB_CMD.<br />&nbsp;<br />MOVE gggggggggggggggg TO TWA-KEY-VALUE.<br />&nbsp;<br />PERFORM AA840-CALL-MAGEC-IO THRU AA899-EXIT.<br />&nbsp;<br />where gggggggggggggggg = the desired actual gateway name to be substituted. The I/O module will dynamically substitute (cont.)<br />that name for the word VARIABLE at the time the file is opened (first accessed). That gateway name will remain (cont.)<br />associated to that file (DCL) until the file is closed as a result of a CLOSE, CLSFL, or **CLSE command, or the end of (cont.)<br />the task. A task ends whenever an online program returns to the control program to have the screen sent, or when a (cont.)<br />batch program reaches end-of-job and executes a GOBACK (or STOP RUN).<br />The I/O module will retain the current setting given in the SETVG (set variable gateway) command and will use it for (cont.)<br />all files having a gateway name of VARIABLE which are opened thereafter until another SETVG command changes the value. (cont.)<br />To "unset" the value, issue SETVG with a name of "VARIABLE" in TWA-KEY-VALUE.<br />If you need to access one file on one gateway, and another on another (both files being specified with gateway names of (cont.)<br />VARIABLE), you can issue SETVG, access the first file, then issue another SETVG and access the second file, et (cont.)<br />cetera.