SAMPLES - cfsoftware.com · Samples of both types of transfer are included in this chapter. Preparing for Host Initiation There are setup and configuration requirements that must

pcMAINFRAME™

SAMPLES

cfSOFTWARE, Inc.

pcMAINFRAME Version 5.40©2000 cfSOFTWARE, Inc.

All Rights Reserved

cfSOFTWARE , Inc.2454 E. Dempster

Suite 201Des Plaines, IL 60016

(847) 824-7180www.cfsoftware.com

pcMAINFRAME SAMPLES Contents • i

Contents

Chapter 1 - Introduction 1

Chapter 2 - Host Initiation 3Preparing for Host Initiation ........................................................................................3VTAM Definitions.......................................................................................................4PC Requirements .........................................................................................................5Setup for Direct TCP/IP Connections ..........................................................................6Start APPX TPN Services............................................................................................8Setup for LU6.2 Connections.......................................................................................8Host Initiation - Transfer files in Batch .......................................................................9Host Initiation - Start a CICS or TSO Transfer..........................................................11Host Initiation - Controlled Transfer..........................................................................11Host Initiation and CICS/TSO PC Defined Transfer .................................................14Host Initiation - Waiting for the PC Return Code......................................................15

Chapter 3 - Record Selection, Summarization and Formatting 17Record Description ....................................................................................................18Profile Definitions......................................................................................................18

Chapter 4 - Advanced Compression 21Using Advanced Compression ...................................................................................21Mainframe Configuration...........................................................................................21PC Configuration .......................................................................................................22

Chapter 5 - Multiple File Support 25Simple Field Combine ...............................................................................................25Generic Access - Direct .............................................................................................29Generic Access - Sequential.......................................................................................32

ii • Contents pcMAINFRAME SAMPLES

pcMAINFRAME SAMPLES Chapter 1 - Introduction • ��

Chapter 1 - Introduction

pcMAINFRAME offers the user a wide variety of advanced file transfer options inaddition to its more direct file transfer capabilities. These include:

• Host initiated file transfers

• Record selection, summarization, and reformatting

• Advanced Compression

• Multiple File Support

This manual contains fully annotated examples of the setup files, profiles and dialogscripts that are needed to implement the above features. It is intended to give you a‘quick start’ on making use of these functions and as a supplement to the othermanuals.

In depth explanations of how to install, configure, and run pcMAINFRAME arecontained in the pcMAINFRAME Installation Guide, System Administrator’s Guide,PC Administrator’s Guide and PC Users Guide. See them for full explanations.

�� •Chapter 1 -Introduction pcMAINFRAME SAMPLES

pcMAINFRAME SAMPLES Chapter 2 - Host Initiation • ��

Chapter 2 - Host Initiation

The pcMAINFRAME host initiation facility allows you to start and control filetransfers via a mainframe batch application. This facility can be used to initiate twotypes of transfer processing.

1. Batch Transfers are handled entirely by the batch application. The file(s) beingtransferred are sent or received by the mainframe job.

2. Controlled Transfers are pcMAINFRAME CICS transfers that are started by themainframe job. In this type of transfer, the mainframe sends ‘transfer control’information’ to the PC, then drops its connection to the PC. The PC will thenconnect to a specified CICS region, run any transfers requested, logout of CICSand optionally, re-establish the connection to the mainframe job to send it areturn code.

Samples of both types of transfer are included in this chapter.

Preparing for Host InitiationThere are setup and configuration requirements that must be in place before a hostinitiated transfer can be run, based on the connection type to be established. Thefollowing table summarizes the mainframe and PC components that must be installedor updated for correct processing of host initiated transfers.

Connection Requirements Further Reference

Direct TCP/IP Mainframe:

TCP/IP for MVS or TCP/IP for VSEwith TCP/IP connectivity to thetarget PC.

PC:

APPX TPNS installed, configuredand running with the TPN defined forpcMAINFRAME.

APPX Listener device driver selectedin Setup file.

IBM TCP/IP manuals

PCMF Users Guide.

APPX TPN ServiceImplementation Guide.

�� •Chapter 2 -Host Initiation pcMAINFRAME SAMPLES

Connection Requirements Further Reference

LU2 (any typeof 3270connection)

Mainframe:

VTAM definitions for CFXINIT.

PC:

Active terminal session at a ‘USS’screen.

MAINW running in ‘waiting forhost’ mode.

PCMF Installation Guide

IBM VTAM manuals

PCMF PC Users Guide

LU6.2 Mainframe:

VTAM definitions for CFXINIT.

VTAM and SNA definitions toprovide the LU6.2 connection to thetarget PC.

PC:

LU6.2 stack installed, configured andactive.

TPN for pcMAINFRAME definedin the LU6.2 stack.

LU6.2 configuration file for PCMF.via MAINCON.

PCMF Installation Guide

IBM SNA/LU6.2 manuals

Gateway Server reference

PCMF PC AdministratorsGuide

A brief description of the setup and configuration requirements for both the PC andmainframe are included below.

VTAM DefinitionsThe program that performs host initiation and transfers, CFXINIT, uses VTAM toestablish 3270 or LU6.2 sessions. Note. VTAM is not needed for direct TCP/IPconnections.

If VTAM is used, one or more VTAM table definitions must be defined beforeCFXINIT can run. The definitions are described in full in the pcMAINFRAMEInstallation manual.

You must add one or more new application IDs to an existing VTAM applicationmajor node or a new application major node. You will need one application ID foreach concurrent execution of CFXINIT. If you plan to run three concurrent transfers,you will need three IDs. You can name these IDs anything that you wish.pcMAINFRAME will automatically increment the low order portion of the name todynamically select an available ID if you name them with similar high order portions.Below is a sample set of definitions:

VTMAPPL5 VBUILD TYPE=APPLHIFAP01 APPL AUTH=(PASS,ACQ),MODETAB=modetabHIFAP02 APPL AUTH=(PASS,ACQ),MODETAB=modetab..HIFAP09 APPL AUTH=(PASS,ACQ),MODETAB=modetabHIFAP10 APPL AUTH=(PASS,ACQ),MODETAB=modetab

The value for MODETAB should be whatever mode table your installation uses. Ifyou use the default table, leave this parameter off.

For LU6.2 connections, see the pcMAINFRAME Installation Guide for additionalinformation on VTAM definitions.


PC Requirements

Setup File

When pcMAINFRAME is installed, a sample setup file called SETINIT.PCM and anicon for PCM Init is created. Note. For direct TCP connections, the setup filereferenced will be INITTCP.PCM.

The file is used to run the PC side of host initiated transfers. It may be modified tosuit your communications environment and your processing requirements.

For a direct TCP/IP or a LU6.2 connection, the setup file does not normally need tobe updated. For LU2 (3270) connections, the setup file is commonly modified toprovide a PROLOG script that will acquire the 3270 session and navigate to theVTAM USS screen.

To modify the SETINIT.PCM file;

• Double click on the pcMSETUP icon.

• Select File/Open for file ‘SETINIT.PCM’.

Figure 2-1: Host Init Setup File, Parameters screen

The example above illustrates a TN3270 connection. The ‘Wait for Host - Multiple’setting in the menu bar Options selection is defaulted on. This setting causes the PCapplication to stay active after a transfer session and wait for the next request fromthe host.

The Prolog section of the setup file is used to automate the keystrokes needed tonavigate to the proper USS screen. The sample below shows a script that will obtaina TN3270 session on startup, and continue to use the session while MAINW isrunning in host initiation mode.

Check this for hostinitiated transfers.


Figure 2-2: Prolog Script

To view or modify the prolog script, activate the Script window, then

• Press the Prolog button on the bottom of the Window.

• Enter any required script commands. The commands at this locationwill execute before pcMAINFRAME waits for host initiation. Theterminal session must be ready at a USS screen (VTAM menu). Scriptany commands necessary to get to this point.

The Epilog script will be run after a transfer session is finished. Usually, no script isnecessary, but if desired, it can be used to copy or rename files, launch a new PCapplication, etc. Note, while the Epilog is running, a new transfer from the hostcannot be started, as the terminal is ‘busy’ processing the script.

To view or update the Epilog script, click on the Epilog button at the bottom of theScript window.

After any changes to the setup file are completed, Select File/Save or saveAs fromthe menu bar to save the changes. If you change the file name, you must change thefile reference on the PCM Init icon.

Setup for Direct TCP/IP ConnectionsFor direct TCP/IP connections, MAINW is started whenever a host sends a filetransfer request to the PC. The APPX TPN Service manager must be running to waitfor (listen for) incoming traffic and start the transfer program. The TPN servicemanager must be configured and started before transfers can take place.

A default TPN Service configuration file was created when APPX TPNS wasinstalled. This file should be reviewed and modified if necessary. The APPX TPNSconfiguration has two parts: Listeners and TPN Definitions.

1. The TPN Definition defines MAINW.EXE as the program that will berun for those clients.

2. The Listener section defines the TCP/IP ports that will accept aconnection from the mainframe transfer program.


To review the file created for you at install, open the APPX TPNS ServiceConfiguration icon in the pcMAINFRAME program folder. Select File andOpenActive from the Menu Bar. The ‘Active’ configuration is used when the TPNservice Manager is started.

Figure 2-3: TPN Configuration - Global Settings

To update these settings, select Edit / Properties from the menu bar, or click on theproperties icon on the tool bar. The “Start TPN Service Automatically” option shouldbe checked. This will automatically start the TPN service manager when theworkstation is started. Normally, other values here do not need to be changed.

Next, select the TPN Definition “MAINW” to display the default TPN values.

Figure 2-4: Default TPN values for MAINW

The TPN is set to run program MAINW.EXE on the PC, with the default setup file,INITTCP.PCM that was created during installation. Change the directory only ifpcMAINFRAME was installed in a directory other than the default.

To display listener connection information, highlight a listener Port address.

Parms associated withTPN MAINW include thedirectory, program andsetup file to use when theTPN is requested. If youdid not install into thedefault directory, thesemust be changed.


Figure 2-5: TPNS Port configuration

Data for each listener defines the TCP/IP port address that will be used to wait forincoming connections. The assignment is arbitrary, but should be in a range from1025-65534. The mainframe application CFXINIT use this port number, as well asthe actual TCP/IP address, to direct transfer data to the PC.

After configuration data is reviewed and updated as necessary, select File and SaveAs Active.

Start APPX TPN ServicesThe APPX TPN Service Manager is used to control TPN sessions. It is uses theActive configuration file to start the TPN service and individual listeners.

To start the Service Manager manually, double click the “APPX TPN ServiceManager” icon from the pcMAINFRAME program folder. From the ServiceManager menu bar, select Action / Start APPX TPN Service to start the TPN service.While the APPX TPN Service is running, there is normally a taskbar icon ( )visible in the task tray.

At this point, the PC is ready to process transfers.

Setup for LU6.2 ConnectionsFor LU6.2 connections, the transfer application will be started when the hostestablishes an LU6.2 session on the PC. For detailed information on LU6.2configuration requirements, see the PC Administrators Guide - ConfigurationChapter.

The default port may bechanged by the mainframe.If so, this parameter mustbe updated.


Host Initiation - Transfer files in BatchA host initiated batch transfer transmits entire files to and from your PCs. The files tobe processed are allocated in the batch job, and control statements are used to defineconnection and specific transfer values. All transfer processing takes place using theterminal or TCP/IP connection initially acquired by the batch job.

Host Mainframe

Cl ient PC

Batch Job- Init iates- Transfers- Controls

Figure 2-6: Host Initiation - Batch Transfer

For LU2 (3270) connections, MAINW.EXE must be started on the PC. If you arerunning with an LU6.2 or a direct TCP/IP connection, then the PC must beconfigured as described previously. The examples below show the connectstatements needed for each supported type of connection.


MVS JCL

//HOSTINI1 JOB (acct) //* HOST INITIATION AND BATCH TRANSFER //JOBLIB DD DSN=PCMAIN.LOADLIB,DISP=SHR //* //STEP1 EXEC PGM=CFXINIT //REPORT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //DATA1 DD DSN=PCM.TEST3.CFXESDS,DISP=SHR //INPUT DD * //* CONNECT LUNAME(HCF01203) APPLID(HIFAP01)//* CONNECT // TCP/IP connection TCPIP(YES) HOST(tcp.ip.address) PORT(2500)//* CONNECT LU62(YES) LUNAME(SLU-NAME) APPLID(HIFAP01)DOWNLOAD DEVI(ESDS) DDNAME=(DATA1) PCFILE(C:\PCM_WIN\SALES.DAT) /* // * $$ EOJ

Figure 2-7: MVS - Initiate from host and transfer a file

VSE JCL

* $$ JOB JNM=HOSTINI1,CLASS=0,DISP=H // JOB HOSTINI1 BATCH TRANSFER TO PC // LIBDEF *,SEARCH=(CFSOFT.PROD4,CFSOFT.TEST4) // ASSGN SYS003,SYSRDR // ASSGN SYS090,SYSLST // DLBL ESDSIN,'PCM.T.EF3.FILE',,VSAM,CAT=CFSCAT // EXEC CFXINIT

CONNECT LUNAME(HCF01203) APPLID(HIFAP01)//* CONNECT // TCP/IP connection TCPIP(YES) HOST(tcp.ip.address) PORT(2500)//* CONNECT LU62(YES) LUNAME(SLU-NAME) APPLID(HIFAP01)

DOWNLOAD DEVI(ESDS) PCFILE(C:\PCM_WIN\SALES.DAT) /** $$ EOJ

Figure 2-8: VSE - Initiate from host and transfer a file

3270 Connect Statements1. The VTAM LU Name of the

PC terminal to send data to.2. The 1st of the APPLIDs

defined to VTAM forCFXINIT.

TCP/IP Connect Statements1. TCP/IP connect indicator.2. The TCP/IP address of the PC to send data to.3. The TCP/IP port that the PC’s TPN Service is

listening on for CFXINIT.

LU6.2 Connect Statements1. LU6.2 connect indicator2. APPC/LU6.2 name assigned

to the target PC.3. The 1st of the APPLIDs


TCP/IP Connect Statements1. TCP/IP connect indicator.2. The TCP/IP address of the PC to send data to.3. The TCP/IP port that the PC’s TPN Service is

listening on for CFXINIT.LU6.2 Connect Statements1. LU6.2 connect indicator2. APPC/LU6.2 name assigned

to the target PC.3. The 1st of the APPLIDs


3270 Connect Statements1. The VTAM LU Name of the

PC terminal to send data to.2. The 1st of the APPLIDs defined

to VTAM for CFXINIT.


Host Initiation - Start a CICS or TSO TransferpcMAINFRAME allows you to initiate, from a batch job, a transfer that takes placefrom CICS or TSO, rather than from the batch job itself. The data to be transferred isstill specified by the job that initiates the transfer, but the actual data transfer occursunder the control of CICS or TSO.

Client PC

CICS or TSO- Transfers

The mainframedisconnects fromthe terminalsession.

Cl ient PC Client PC

Batch Job- Initiates- Defines- EOJ if(NOWAIT)

The PC uses theterminal session tolog on to CICS orTSO, and log off atthe end of transferprocessing.

Batch Job- EOJ with PCReturn Code(WAIT) only

The PCreconnects to themf batch job andsends transferReturn Code.

Figure 2-9: Host Initiation - Start a CICS or TSO transfer

This option would be used when your data exists in files that are updated online, or ifyou need to use a PROFILE to perform special processing on the data to betransferred, such as record selection, field selection, data reformatting, and file typereformatting.

When the host initiates a transfer to run in CICS or TSO, you have the choice howthe transfer will be defined. The host initiation program may specify some or all ofthe transfer information, or it may rely on the information that is stored on the PC inthe setup file.

Host Initiation - Controlled TransferThe next examples show host initiated transfers with the mainframe statementsneeded to specify the profile name and the PC file name to be used for the transfer.

The host program connects to the PC, downloads the transfer information, thendisconnects from the terminal session and goes to End-of-Job. Since the WAITparameter is not defined, the mainframe process is complete as soon as it has finishedsending the transfer instructions to the PC.


Setup Changes

Since the PC is going to use CICS to run the transfer, additional information isneeded in the setup file, including the pcMAINFRAME User ID and password, aStartscript to sign the PC on to CICS and an Endscript to logoff of CICS.

The following show the changes needed in a setup file to run a CICS or TSO transferthat is initiated by the host. Note. If the connection to be made to the mainframe isdirect TCP/IP, then the scripts are not required.

Figure 2-10: Parameters for Host Initiated Controlled transfer

The Startscript defined below will sign the user into CICS after the host job has sentthe transfer instructions to the PC and disconnected from the terminal session.

Figure 2-11: Startscript - CICS sign-on

This is the PCID’spassword

Automatically sendpassword

History Logging


The Endscript will log off CICS when the transfer is complete.

Figure 2-12: Endscript - CICS sign-off

The above changes should be applied to the setup file that will be used to runcontrolled transfers.

Sample JCL for Controlled Transfers //HOSTINI1 JOB (acct) //* HOST INITIATION AND BATCH TRANSFER //JOBLIB DD DSN=PCMAIN.LOADLIB,DISP=SHR //* //STEP1 EXEC PGM=CFXINIT //REPORT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //INPUT DD *

CONNECT LUNAME(HCF01203) APPLID(HIFAP01) TRANSFERAPPL(CFCICST4)

DOWNLOAD PROFILE(SALES2) PCFILE(C:\PCM_WIN\SALES.WKS)//

Figure 2-13: MVS - Host Initiated CICS transfer

* $$ JOB JNM=HOSTINI1,CLASS=0,DISP=H * $$ LST CLASS=A // JOB HOSTINI1 BATCH TRANSFER TO PC // LIBDEF *,SEARCH=(CFSOFT.PROD4,CFSOFT.TEST4) // ASSGN SYS003,SYSRDR // ASSGN SYS090,SYSLST // EXEC CFXINIT


DOWNLOAD PROFILE(SALES2) PCFILE(C:\PC,_WIN\SALES.WKS) /* * $$ EOJ

Figure 2-14: VSE Host Initiated CICS Transfer

This is the APPLID of the CICS inwhich pcMAINFRAME runs. Whenthis parameter is specified, the hostjob will cause VTAM to logon to thisAPPLID after it releases theterminal.

Sign off CICS andreturn to the VTAMUSS screen


In addition to the download commands used above, you may also specify anysections that normally appear in the setup file. For instance, you can specify one ormore complete transfer sections, a startscript or an endscript. When these sections arespecified, they will be transferred to the PC and will replace any correspondingsection in the PC’s setup file. Note, if any transfer section is defined, all transfersections in the setup file will be replaced.


STARTSCRIPT WAIT 'WELCOME' WAIT RESPONSE SEND PF6 WAIT CLEAR/END* --------------------------- ENDSCRIPT TO SIGN OFF CICS ENDSCRIPT WAITFOR RESPONSE SEND RESET CLEAR WAIT CLEAR SEND 'CSSF LOGOFF' ENTER WAITFOR RESPONSE/END* --------------------------- TRANSFERS TRANSFER TRANSFERID=TEST DOWNLOAD FUNCTION=DOWNLOAD PROFILE=LIB PCFILE=C:\PCM_WIN\INIT.LIB LIBPASS=MYPASSWD/END TRANSFER TRANSFERID=TEST DOWNLOAD FUNCTION=DOWNLOAD PROFILE=LIB PCFILE=C:\PCM_WIN\INIT.LIB LIBPASS=MYPASSWD/END

Figure 2-15- Host Initiated CICS transfer with setup file overrides

Host Initiation and CICS/TSO PC Defined TransferIf there are no transfer commands present in the initiation job step then the PC willperform whatever actions are defined in the setup file on the PC. In this case, theCFXINIT step is merely a trigger to start the predefined activity on the PC. Values forthe variables used in the setup file may be transmitted along with the initiation.

VSE JCL * $$ JOB JNM=HOSTINI1,CLASS=0,DISP=H * $$ LST CLASS=A // JOB HOSTINI1 BATCH TRANSFER TO PC // LIBDEF *,SEARCH=(CFSOFT.PROD4,CFSOFT.TEST4) // ASSGN SYS003,SYSRDR // ASSGN SYS090,SYSLST // EXEC CFXINIT CONNECT LUNAME(HCF01203) APPLID(HIFAP01) TRANSFERAPPL(CFCICST4) VARIABLE &JOBNAME=ILSALES * /& * $$ EOJ

Figure 2-16:: VSE Host Initiated CICS Controlled Transfer with Variables

This startscript will replace theone on the PC.

The setup file on the PC has aPOWER download defined in its[TRANSFER] section.

The JOBNAME variable in thesetup file will resolve with thespecified ‘ILSALES’.

This endscript will replace theone on the PC.

These transfers will replace alltransfer sections on the PC.


Host Initiation - Waiting for the PC Return CodeThe mainframe job may obtain the status of the CICS transfers that were initiated bythe JOB. If the WAIT(nnn) parameter is coded in the CONNECT section, themainframe job will wait up to the specified number of minutes for the PC toreconnect to the job and send result information.

If the transfer is not successful, or if the PC was unable to report back to themainframe, a return code of 8 will be set for the job step.

The return code can be tested to control execution of the rest of the JOB. Thefollowing is an example of a VSE JOB using JCL to notify the operator if acontrolled transfer was not successful.

VSE JCL* $$ JOB JNM=INITRC,CLASS=0* $$ LST CLASS=A// JOB INITRC - HOST INIT RETURN CODE CHECKING// SETPARM LUID=SYS40000,GO=N// OPTION PARTDUMP,NOSYSDMP// ON $RC=16 GOTO ERR16/* --------------------------------------------------------------*/* HOST INITIATION - RETURN CODE CHECKING/* --------------------------------------------------------------*// LIBDEF *,SEARCH=CFSOFT.PROD4// ASSGN SYS081,SYSLST// EXEC CFXINIT,PARM='LUNAME(&LUID)' CONNECT APPLID(HIFAPPL) WAIT(50) TRANSFERAPPL(CICSPROD) DOWNLOAD PCFILE(C:\SALES\SALESUM.XLS) PROFILE(SALES2)/*// IF $RC=0 THEN// GOTO RUN2/* --------------------------------NOT OK1, SEND MSG TO OPERATOR// PAUSE JOB INITRC FAIL: ENTER //SETPARM GO=Y TO RUN NEXT STEP// IF GO=N THEN// GOTO ENDUP/* --------------------------------TRANSFER #2 - NEW SALES/. RUN2// SETPARM LUID=SYS40021// DLBL ESDSIN,'PCM.T.EF1.FILE',,VSAM,CAT=CFSCAT// ASSGN SYS031,DISK,VOL=SYSWK1,SHR// ASSGN SYS081,SYSLST// EXEC CFXINIT,PARM='LUNAME(&LUID)' CONNECT APPLID(HIFAPPL) DOWNLOAD DEV(ESDS) PCFILE(C:\SALES\SALESNEW.DAT)/*// IF $RC=0 THEN// GOTO ENDUP/* --------------------------------NOT OK2, SEND MSG TO OPERATOR// PAUSE JOB INITRC FAIL @STEP2 - CHECK LOGS AND RERUN// GOTO ENDUP/* --------------------------------ENDUP (EOJ)/. ERR16/* --------------------------------SYNTAX ERROR IN COMMAND SET// PAUSE JOB INITRC FAIL SYNTAX ERROR(S). CORRECT AND RERUN// GOTO ENDUP/* --------------------------------ENDUP (EOJ)/. ENDUP* $$ EOJ

Figure 2-17: VSE Host Initiated JOB with Return Code checking


pcMAINFRAME SAMPLES Chapter 3 - Record Selection, Summarization and Formatting • ��

Chapter 3 - Record Selection,Summarization and Formatting

pcMAINFRAME can select records and extract all or some fields from the selectedrecords. In addition, data in a logical group of records can be summarized beforedownloading. The desired PC file format, (dBASE, WKx, etc.) can be specified.

This sample demonstrates the use of these features.

Assume a KSDS Sales Master file that contains detail regarding the sales ofcomputer equipment. There is a data record for each sale. The file is organized byRegion, District and Branch office.

The sales department wants the following information in spreadsheet format:

For each Branch Office:The total number of sales, the total sales amount and the average sale amount foreach product for a given month or quarter.

The master file record layout and the profile definition used to accomplish thedownload follow.

Note, the profile “SALES2” that is shipped with pcMAINFRAME and is used tocheckout the installation process is similar to this sample.

�� •Chapter 3 -Record Selection, Summarization and Formatting pcMAINFRAME SAMPLES

Record Description

Sales Master.

01 SALES-RECORD.

05 SALES-KEY.

10 SALES-REGION PIC 9(2).

10 SALES-DISTRICT PIC 9(2).

10 SALES-BRANCH PIC 9(4).

10 SALES-PRODUCT PIC X(6).

10 SALES-KEY-SEQ PIC S9(4) COMP.

05 SALES-DATE PIC X(6).

05 SALES-DOLLARS PIC S9(9)V99 COMP-3.

05 SALES-UNITS PIC S9(5) COMP-3.

05 SALES-DESCRIPTION PIC X(30).

05 SALES-BILL-CD PIC X.

05 FILLER PIC X(62).

Profile DefinitionsThe first screen of the profile definition defines the mainframe file to be used for thetransfer, transfer direction , output data format and other basic information about thetransfer.

_______________________________( pcMAINFRAME )________________________________ Profile Definition Page 1

Profile Name......... SALESSUM Name of this definition Profile Description.. SUMMARIZE SALES BY BRANCH Password (optional). NONE (NONE) If no password required Profile class........ A A-Z, * for all classes File or Exit name.... CFXKSDS FCT or PPT or DDNAME entry name File type............ KSDS ESDS/KSDS/RRDS/Lib/Publ/Exit/QSAM/PDS Output data format... L EXCEL B, D, F, T, S, W, X, I, L, A Transfer direction... D (U)p, (D)own, (B)oth ways

Generate column headers (Y/N). Y Translation modes U, W, or M.. U Read limit (Maximum reads).... 0 Write Ctrl_Z at EOF (Y/N)..... N Write limit (Maximum writes).. 0 Make blank fields Null (Y/N).. N Skip Type B (Before) Count.. 0 Multiple Record Header (Y/N).. N Fixed rec length (optional)... Last maint/used dates: 12/15/94 12/29/94 Download count limit.......... 0

Profile found - Update assumed.

PF1 - Return to directory, PF2 - Next Page, Clear - Menu.

Figure 3-1: Initial Profile Definition

pcMAINFRAME SAMPLES Chapter 3 - Record Selection, Summarization and Formatting • ��

The second screen is used to define the record selection criteria. In this case, a daterange (LO / HI) is specified. Note, that when a data type ‘Date’ is defined,pcMAINFRAME assumes MMDDYY format. During range checking, the date isinternally converted to allow for a valid date range comparison.

In this sample, the from and to dates have been defined as ‘variables’. When thetransfer is run, the user will be prompted to enter the FROM DATE and TO DATE.Thus, any month or range of months can be selected.

Profile: SALESSUM Profile Definition Page 4 Record Selection

Data/Field I Begin Data Dec Name D Pos Bytes Type Plc Action If Comparison Value DATE 25 6 D I LO &FROM DATE (MMDDYY) D HI &TO DATE (MMDDYY)

Commands: >A - Insert after, >B - Insert before, = - Duplicate, < DeletePF1 - 1st page, PF2 - Next Page, PF3 - Prior Page, CLEAR - Menu.

Figure 3-2: Record Selection

The third screen is used to define break criteria. This is a unique feature provided bypcMAINFRAME. When break control is defined, then a ‘summary’ record isextracted each time the defined break occurs. In this way, a series of records can beselected for processing, data in the records can be summarized and a single recordwith the accumulated totals will be downloaded.

In this example, a break will occur whenever a new REGION or DISTRICT orBRANCH or PRODUCT is encountered. Breaks are normally defined only when thefile is sorted or KEYED in the proper sequence.

__________________________________(pcMAINFRAME)__________________________________Profile: SALESSUM Profile Definition Page 4

Break Control

Data/Field Begin Data Dec BreakName Pos Bytes Type Plc If Comparison ValueREGION 1 2 N ANY (Any break in field)DISTRICT 3 2 N ANY (Any break in field)BRANCH 5 4 N ANY (Any break in field)PRODUCT 9 6 C ANY (Any break in field)

Commands: >A - Insert after, >B - Insert before, = - Duplicate, < - Delete.PF1 - 1st page, PF2 - Next Page, PF3 - Prior Page, CLEAR - Menu.

Figure 3-3: Break Control

�� •Chapter 3 -Record Selection, Summarization and Formatting pcMAINFRAME SAMPLES

The final screen, output format, defines the fields on the mainframe file that will bedownloaded to the PC, as well as any internally generated fields to be downloaded.The fields should be defined in the order in which they are to appear in the PC file.

In the screen below, the first four key fields of the input record will be transferred tothe PC file, as well as the product description. Since this profile defines record breaksand a PC file record is extracted only when a ‘break’ occurs, the data fields can bemoved from either the first (default) or last record in the group. In this case, the fieldsare all identical until the break, so it makes no difference.

The next three fields are developed during record processing. The SUM, AVERAGEand COUNT operations are allowed whenever break control is defined. SUM simplyaccumulates the field amount in each record until a break, AVERAGE accumulatesand averages the field amount in each record until a break, and COUNT adds 1 to acounter for each record selected.

In this sample, the TOTAL SALES, AVG SALES and SALES COUNT fields will becalculated and extracted for each Region/District/Branch/Product set of records.

__________________________________(pcMAINFRAME)__________________________________Profile: SALESSUM Profile Definition Page 5

Output Format

Data/Field Begin ___MF____ ___PC____ Dec Name Pos SizeType Size Type Plc Operation Picture / Inserted Data

REGION 1 2 N 2 N MOVE Numeric S9(2)DISTRICT 3 2 N 2 N MOVE Numeric S9(2)BRANCH 5 4 N 4 N MOVE Numeric S9(4)PRODUCT 9 6 C 6 C MOVE Alpha/Num X(6)DESCRIPTION 32 32 C 32 C LAST Alpha/Num X(32)TOTAL SALES 23 6 P 15 N 2 SUM Packed S9(9)V9(2)AVG SALES 23 6 P 15 N 2 AVERAGE PackedS9(9)V9(2)SALES CNT 4 N COUNT (count to break)

Commands: >A - Insert after, >B - Insert before, = - Duplicate, < - Delete.PF1 - 1st page, PF2 - Next Page, PF3 - Prior Page, CLEAR - Menu.

Figure 3-4: Output Format

pcMAINFRAME SAMPLES Chapter 4 - Advanced Compression • ��

Chapter 4 - Advanced Compression

Data compression can have a significant impact on the throughput of transfers. Aprime factor in the length of time a transfer takes is the amount of data that must besent. Compression reduces the amount of data that is transferred and thereby reducestransfer times.

pcMAINFRAME by default compresses all data sent between the PC and mainframe.The technique used is a form of compression called run length encoding or RLE.This replaces strings of any repeating character with a short code that indicates howmany occurrences of the character are being replaced. This technique’s effectivenessis dependent on the data. If there are no repeating characters no compression willoccur. If there are a large number of repeating characters compression can be quitegood. Printouts, fixed format records and text files compress well with this technique.

pcMAINFRAME provides an optional, advanced compression option that utilizes thepatented Lempel, Ziv, Welch technique or LZW. This is an adaptive compressiontechnique that builds a dictionary of repeating variable length strings. Repeatedoccurrences of those strings are replaced with short codes. This is the type ofcompression used by popular PC based compression programs and most MNP5 andV.42 modems. While the performance of this technique is affected by the data, itgenerally performs significantly better than RLE does on the same data.

Using Advanced CompressionAdvanced compression must be enabled on both the mainframe and the PC in orderfor it to be used. The figures below show you how to turn on this feature on themainframe and the PC.

Mainframe ConfigurationBefore you start this procedure, call cfSOFTWARE to enable the trial period foradvanced compression. The compression option is enabled with the followingprocedure:

• Log on to the CICS in which you run pcMAINFRAME.

• Type: PCMM �(QWHU�. This will bring up the pcMAINFRAME menu.

• Press: �3)�� This brings up the Options Customization Screen

�� •Chapter 4 -Advanced Compression pcMAINFRAME SAMPLES

• Enter ** in both the Upload and Download Compression Methodsfields. This value sets the mainframe compression option to whatevervalue is received from the PC. With ** as the value the PC controls thecompression function.

• Enter a U in the Enter U to Update field and press �(QWHU�.

• Press �&OHDU� twice to get back to CICS.

_______________________________( pcMAINFRAME)________________________________ Options Customization

Class Codes.................. 01 01 01 01 01 01 01 01 Hardcopy Log Destination..... CSMT DCT for hardcopy transmissionlog Security Exit name........... PPT of the Security exitprogram Activity logging............. Y (Y)es, (N)o, (O)nline,(H)ardcopy Issue Handle Abend........... Y (Y)es, (N)o Host Language................ 1 English 1 thru 7 3270 block size.............. 1920 0 or 100 thru 3564 bytes Protocol converter blk size.. 512 0 or 100 thru 3564 bytes Advanced Exit Support........ N (Y)es, (N)o Syncpoint record limit....... 0 Compression Methods: Upload: ** Download: **

U Enter (U) to Update.:

Depress: Clear - Return to Menu - no update

Figure 4-1: Compression Options in Host Configuration

PC ConfigurationEnabling advanced compression on the PC is automatic, but setup files default to A2compression for downloads only. To enable compression for both uploads anddownloads, the setup file must be updated.

• Start pcMSETUP by double clicking its icon.

• Open the setup file that you wish to use.

• On the Parms window, change the compression option to the desiredvalue.

Update these fields to **

pcMAINFRAME SAMPLES Chapter 4 - Advanced Compression • ��

Figure 4-2 : PC Compression Configuration

You may also change the compression method for optimum performance.

• On the Parms window, click the Advanced Parms button.

• Enter the desired methods and size options and then click on the OKbutton. Use A4 to obtain the largest compression library possible.

• Save the updated setup file.

Figure 4-3: Configuring Compression Method

Compressiondirection.

Compression Methodand buffer size.

�� •Chapter 4 -Advanced Compression pcMAINFRAME SAMPLES

pcMAINFRAME SAMPLES Chapter 5 - Multiple File Support • ��

Chapter 5 - Multiple File Support

pcMAINFRAME can select and combine data from multiple files in a singledownload. This permits you to download all of the data that logically goes togetherinto a single output file.

The following sections will demonstrate the various types of Multiple File processingavailable: Simple field Combine, Generic Access - Direct, and Generic Access -Sequential (Join process).

Simple Field CombineThis sample demonstrates downloading of an inventory record combined withinformation from an item master file and a vendor master file. The item master recordis retrieved using an item number defined in the inventory file and the vendor masteris retrieved using vendor number that is defined in the item master record.

The following sections demonstrate the set up of a profile to transfer the inventoryrecords along with associated information from the item master file and the vendormaster file. The record layouts are described followed by an annotated profile.

Record Descriptions

Inventory Detail Record01 INVREC.

05 INVREC-KEY.10 INV-PLANT PIC S9(5).10 INV-ITEM PIC S9(9).

05 INVREC-LOC.10 INV-AISLE PIC S9(3).10 INV-ROW PIC S9(3).10 INV-BIN PIC S9(3).

05 INVREC-COUNT PIC S9(7) COMP 3.05 INVREC-DATE PIC S9(7) COMP 3.

�� •Chapter 5 -Multiple File Support pcMAINFRAME SAMPLES

Item Master Record01 ITEMREC.

05 ITEMREC-KEY.10 ITEM-NUMBER PIC S9(9).

05 ITEM-DESCRIPTION PIC X(35).05 ITEM-UNIT PIC X(5).05 ITEM-VENDOR PIC S9(7).

Vendor Master Record01 VENDREC.

05 VENDREC-KEY.10 VEND-VENDOR PIC S9(7).

05 VEND-NAME PIC X(35).05 VEND-ADDR1 PIC X(35).05 VEND-ADDR2 PIC X(35).05 VEND-CITY PIC X(35).05 VEND-STATE PIC X(2).05 VEND-PHONE PIC S9(11) COMP 3.05 VEND-FAX PIC S9(11) COMP 3.

Profile

In this sample, the Inventory Master is considered the primary file. Its characteristicsand FCT are defined in the first profile definition screen just as any other profile. TheItem Master and Vendor Master are considered ‘secondary files ‘, and are defined inthe Multiple File Definition screen shown below.

_______________________________( pcMAINFRAME )________________________________ Profile: SAMPLMFS Profile Definition Page 3 Multiple File Definition

*Identification* *-------Key Fields-------* *--------Source Fields--- I File File Field Begin Fld T I Begin Fld T D Name Type Name Pos Lngth P D Pos Lngth P Literal Data A ITMMAST KSDS ITEMNUM 1 9 N * 6 9 N B VNDMAST KSDS VENDOR 1 7 N A 46 7 N

Define Secondary Files and Access Key data From 1 to 6 files are allowed.

Commands: >A - Insert after, >B - Insert before, = - Duplicate, < - Delete. PF1 - 1st page, PF2 - Next Page, PF3 - Prior Page, Clear - Menu.

Figure 5-1: Profile Multiple File Definition

The screen is used to specify the following.

• The name (FCT or DDNAME) of the secondary file

• The location and data type of all key fields in the secondary file

• The location of the field(s) in the primary or secondary records thatcontain the actual key data.

The actual key data fields must reference ONLY fields in the primary file or apreviously defined secondary file. Thus a key field for secondary file B can be

Indicates which recordand location that thekey is picked up from.

Location of keyin record

IDs define eachsecondary file tobe accessed.


obtained from any field in the primary record or any field in secondary file A, but notfrom secondary file C.

Once the secondary files are defined, any field in the secondary records can bereferenced in subsequent screens. The ID field that follows the name field is used topoint to the secondary file. In the following record selection screen, PLANT isdefined in the primary record and does not need an ID, but VEND-STATE is definedin the vendor master (secondary file “B”) and therefore is coded with a “B” in the IDfield.

_______________________________( pcMAINFRAME )________________________________ Profile: SAMPLMFS Profile Definition Page 4 Record Selection

Data/Field I Begin Data Dec Name D Pos Bytes Type Plc Action If Comparison Value PLANT 1 5 N 0 I = 1005 VEND-STATE B 157 2 C & = AZ

Define Include/Exclude rules... from none to 12 are allowed.


Figure 5-2: Profile Record Selection

_______________________________( pcMAINFRAME )________________________________ Profile: SAMPLMFS Profile Definition Page 6 Output Format Data/Field I Begin ___MF____ ___PC____ Dec Name D Pos Size Type Size Type Pl Operation Picture / Inserted Data PLANT 1 5 N 5 MOVE Numeric S9(5) ITEM 6 9 N 9 MOVE Numeric S9(9) ITEM-DESC A 6 35 C 35 MOVE Alpha/Num X(35) VENDOR-NUM A 46 7 N 7 MOVE Numeric S9(7) VENDOR-NAME B 8 35 C 35 MOVE Alpha/Num X(35) VENDOR-PHONE B 185 5 P 11 MOVE Packed S9(9)


Figure 5-3: Profile Output Format

ID defines whichsecondary thedata field isfrom.

ID defines whichsecondary file theselection field is in


Result

Comb inedData

I tem Number

InventoryDetai l

Vendor Number

I tem Master

VendorMaster

Figure 5-4: Combined Data Record

The output to the PC from the profile defined above would be a file containingrecords made up of data from the three mainframe files. The fields in the record willbe:

Field Source FilePlant Number Inventory DetailItem Number Inventory DetailItem Description Item MasterVendor Number Item MasterVendor Name Vendor MasterVendor Phone Vendor Master

The records downloaded will be inventory items from plant 1005 whose vendor islocated in Arizona.


Generic Access - DirectYou can access a secondary record using a generic key. The read will obtain the firstrecord on the file that has the same starting characters as the data specified. One andonly one record from the secondary file will be obtained for each record selectedfrom the primary.

This section demonstrates the set up of a profile to match a customer number fromthe customer master, and access all invoices for that customer from the invoicemaster. The record layouts are described followed by an annotated profile.

Record Descriptions

Customer Master01 CUST-REC.

05 CUST-KEY.10 CUST-NO PIC 9(9).

05 CUST-INFO.10 CUST-NAME PIC X(30).10 CUST-ADDR.

15 CUST-ADDR1 PIC X(30).15 CUST-CITY PIC X(25).15 CUST-ST PIC X(2).15 CUST-ZIP PIC 9(9).

Invoice Master01 INV-REC.

05 INV-KEY.10 INV-CUST PIC 9(9).10 INV-NO PIC 9(9).

05 INV-DATE PIC X(8).05 INV-DUE-DATE PIC X(8).05 INV-AMT PIC S9(9)V99 COMP-3.


Profile

In this sample, the Customer Master is considered the primary file. Its characteristicsand FCT are defined in the first profile definition screen just as any other profile. TheInvoice Master is considered a ‘secondary file ‘, and is defined in the Multiple FileDefinition screen shown below.

_______________________________( pcMAINFRAME )________________________________ Profile: MFSJOIN Profile Definition Page 3 Multiple File Definition

*--Identification--* *------Key Fields------* *-------Source Fields--------* I File File NF Field Beg Fld T I Begin Fld T D Name Type Rule Name Pos Len P D Pos Len P Literal Data A PCMTKF2 K-GE T CUST 1 9 N * 1 9 N



Figure 5-5: Profile Multiple File Definition - K-GE



• The location and data type of the generic key field(s) in the secondaryfile

• Where the actual key data can be found in the primary record. Note, theactual data can also come form a previously defined secondary record.

The following screen (Output Format) defines the fields that are to be extracted anddownloaded to the PC. Note that CUST _NO and NAME come from the primary file,but INV_NO, INV_DATE, DUE_DATE and AMOUNT come from the invoicemaster file, (secondary file “A”) and therefore are coded with an “A” in the ID field.

_______________________________( pcMAINFRAME )________________________________ Profile: MFSJOIN Profile Definition Page 6 Output Format Data/Field I Begin ___MF____ ___PC____ Dec Name D Pos Size Type Size Type Pl Operation Picture / Inserted Data CUST_NO 1 9 N 9 MOVE Numeric S9(9) NAME 10 30 C 30 MOVE Alpha/Num X(30) INV_NO A 10 9 C 9 MOVE Alpha/Num X(9) INV_DATE A 19 8 C 8 MOVE Alpha/Num X(8) DUE_DATE A 27 8 C 8 MOVE Alpha/Num X(8) AMOUNT A 35 6 P 12 2 MOVE Packed S9(9)V9(2)




Result

The output to the PC from the profile defined above would be a file containingrecords made up of data from the two mainframe files. The fields in each record willbe:

Field Source FileCustomer Number Customer MasterCustomer Name Customer MasterInvoice Number Invoice MasterInvoice Date Invoice MasterInvoice Due Date Invoice MasterInvoice Amount Invoice Master

Cust1 Name InvoiceNo.1 date due date amount

Cust2 Name InvoiceNo1 date due date amount

The record downloaded will be the first invoice (in this case, the OLDEST invoicefor each customer).


Generic Access - SequentialYou can also access one or more secondary records using a generic key withsequential access. This request will obtain all records on the secondary file that hasthe same starting characters as the data specified as the generic key. A record will beextracted and downloaded for EACH matched record on the secondary file, as longas select-include/exclude rules are true.

This section demonstrates the set up of a profile to match a customer number fromthe customer master, and access all invoices for that customer from the invoicemaster. The record layouts are described followed by an annotated profile.

Record Descriptions

Customer Master01 CUST-REC.

05 CUST-KEY.10 CUST-NO PIC 9(9).

05 CUST-INFO.10 CUST-NAME PIC X(30).10 CUST-ADDR.

15 CUST-ADDR1 PIC X(30).15 CUST-CITY PIC X(25).15 CUST-ST PIC X(2).15 CUST-ZIP PIC 9(9).

Invoice Master01 INV-REC.

05 INV-KEY.10 INV-CUST PIC 9(9).10 INV-NO PIC 9(9).

05 INV-DATE PIC X(8).05 INV-DUE-DATE PIC X(8).05 INV-AMT PIC S9(9)V99 COMP-3.


Profile

In this sample, the Customer Master is considered the primary file. Its characteristicsand FCT are defined in the first profile definition screen just as any other profile. TheInvoice Master is considered a ‘secondary file ‘, and is defined in the Multiple FileDefinition screen shown below.

_______________________________( pcMAINFRAME )________________________________ Profile: MFSJOIN Profile Definition Page 3 Multiple File Definition

*--Identification--* *------Key Fields------* *-------Source Fields--------* I File File NF Field Beg Fld T I Begin Fld T D Name Type Rule Name Pos Len P D Pos Len P Literal Data A PCMTKF2 K-BR T CUST 1 9 N * 1 9 N



Figure 5-7: Profile Multiple File Definition - K-BR



• The location and data type of all key fields in the secondary file

• The location of the field(s) in the primary or secondary records thatcontain the actual key data.

The following screen (Output Format) defines the fields that are to be extracted anddownloaded to the PC. Note that CUST _NO and NAME come from the primary file,but INV_NO, INV_DATE, DUE_DATE and AMOUNT come from the invoicemaster file, (secondary file “A”) and therefore are coded with an “A” in the ID field.

_______________________________( pcMAINFRAME )________________________________ Profile: MFSJOIN Profile Definition Page 6 Output Format Data/Field I Begin ___MF____ ___PC____ Dec Name D Pos Size Type Size Type Pl Operation Picture / Inserted Data CUST_NO 1 9 N 9 MOVE Numeric S9(9) NAME 10 30 C 30 MOVE Alpha/Num X(30) INV_NO A 10 9 C 9 MOVE Alpha/Num X(9) INV_DATE A 19 8 C 8 MOVE Alpha/Num X(8) DUE_DATE A 27 8 C 8 MOVE Alpha/Num X(8) AMOUNT A 35 6 P 12 2 MOVE Packed S9(9)V9(2)




Result

The output to the PC from the profile defined above would be a file containingrecords made up of data from the two mainframe files. The fields in each record willbe:

Field Source FileCustomer Number Customer MasterCustomer Name Customer MasterInvoice Number Invoice MasterInvoice Date Invoice MasterInvoice Due Date Invoice MasterInvoice Amount Invoice Master

Cust1 Name InvoiceNo.1 date due date amount

" " InvoiceNo.2 " " "

" " InvoiceNo.3 " " "

Cust2 Name InvoiceNo1 date due date amount

The records downloaded will be all invoices for each customer


This page intentionally left blank

SAMPLES - cfsoftware.com · Samples of both types of transfer are included in this chapter. Preparing for Host Initiation There are setup and configuration requirements that must

Documents