pcMAINFRAME

Guide to Express

cfSOFTWARE, Inc.

pcMAINFRAME Express Version 2.10 Copyright 2000, cfSOFTWARE, Inc. All Rights Reserved

cfSOFTWARE, Inc.
2454 E. Dempster, Suite 201 Des Plaines, IL 60016 (847) 824-7180 www.cfsoftware.com

Table of Contents
Chapter 1 - Introduction 1

Welcome ....................................................................................................................................1 About this Manual......................................................................................................................1 Overview....................................................................................................................................3 Component Summary ..................................................................................................4 Mainframe components ...............................................................................................4 PC components ............................................................................................................4 System Requirements.................................................................................................................5 Mainframe Environment ..............................................................................................5 PC Environment...........................................................................................................5

Chapter 2 - Mainframe Installation

Installation Checklist..................................................................................................................7 VSE Library Restore....................................................................................................7 MVS Library Restore ..................................................................................................8 VTAM Definitions - LU2, LU6.2 and TN3270...........................................................8 JCL Samples ..............................................................................................................10 Installation Verification ...........................................................................................................11 XPVERIFY for VSE .................................................................................................12 XPVERIFY for MVS ................................................................................................13 Submit the Transfer ...................................................................................................13

Chapter 3 - Mainframe Processing

15

Overview..................................................................................................................................15 File Transfer Considerations......................................................................................15 Audit Files .................................................................................................................16 Transfer Control ........................................................................................................17 Return Codes .............................................................................................................18 Return Code Testing ..................................................................................................18 Command File..........................................................................................................................19 Command Syntax.......................................................................................................19 Command File Format ...............................................................................................20 Parameter Descriptions..............................................................................................21 Process Reporting ....................................................................................................................25 Sample Reports..........................................................................................................25 Program Execution...................................................................................................................26 Job Control Language Requirements .........................................................................26 JCL Examples............................................................................................................27

pcMAINFRAME Express

Table of Contents i

Chapter 4 - PC Installation

35

pcmExpress Installation ...........................................................................................................35 Requirements .............................................................................................................35 Installation Process ....................................................................................................35 TCP/IP Listener Installation.....................................................................................................38 Install Online Documentation ..................................................................................................38 Ready for Transfer ...................................................................................................................39

Chapter 5 - PC User Guide

41

Introduction..............................................................................................................................41 Using PCXPRESS ...................................................................................................................41 LU2 (3270) Connections..........................................................................................................41 PROLOG Processing .................................................................................................42 Host Wait State..........................................................................................................43 Direct TCP/IP Connections......................................................................................................43 APPX TPNS Configuration .......................................................................................43 Start APPX TPN Services .........................................................................................45 LU6.2 Connections ..................................................................................................................45 Transfer Processing..................................................................................................................46 Transfer Statistics Window........................................................................................46 Epilog Processing ......................................................................................................47 PC Logging................................................................................................................47 Using PCXSETUP ...................................................................................................................48 To Begin ....................................................................................................................48 Menu Bar Functions ..................................................................................................49 Editing Setup Files.....................................................................................................49 SETUP Screens .........................................................................................................49 Setup file - Structure Overview .................................................................................54 General Rules ............................................................................................................54 Setup File Variables...................................................................................................55 Support Components................................................................................................................56 The CFXATB.INI File ..............................................................................................56 APPX TPN SERVICES.............................................................................................57 Device Configuration.................................................................................................59 Dialog ........................................................................................................................59 Log Reader ................................................................................................................59 Trace Download ........................................................................................................59

Chapter 6 - Messages

61

Troubleshooting .......................................................................................................................61 Pre-Communications Errors.......................................................................................61 Communications Startup Errors.................................................................................62 Errors at Host Connect...............................................................................................62 Errors while running Transfers or PC Scripts ............................................................62 Contacting cfSOFTWARE for Problem Resolution ..................................................62 Messages..................................................................................................................................63 Information Messages................................................................................................63 Mainframe Messages .................................................................................................65 PC Messages..............................................................................................................68 Communications Messages........................................................................................71

ii Table of Contents

pcMAINFRAME Express

Appendix A - Configuration for Commonly used Devices

75

Configuration Overview...........................................................................................................75 Using MAINCON......................................................................................................75 Configuration for HLLAPI Emulators .....................................................................................77 32-bit Emulators ........................................................................................................77 16-bit Emulators ........................................................................................................77 3278/79 Coax Connections ......................................................................................................78 Configuration for TCP/IP - TN3270 ........................................................................................78 Configuration for LU6.2 Connections......................................................................................80 Video Mode and 3270 Keyboard Layout.................................................................................81 CUT Mode 3278/79 Cards ........................................................................................84 16 Bit Windows Emulators........................................................................................84 32 Bit Emulators........................................................................................................84 TCP/IP Connections ..................................................................................................84 LU 6.2 Connections ...................................................................................................85

Appendix B - Custom Translate Tables

87

Defining Custom Translate Tables ............................................................................87 Selecting a Custom Translate Table for Use..............................................................90

Index

91

pcMAINFRAME Express

Table of Contents iii

iv Table of Contents

pcMAINFRAME Express

Chapter 1 - Introduction

Welcome
Thank you for choosing pcMAINFRAME Express. This software provides a fast and easy-to-use mechanism for transferring files from your mainframe to attached PCs. It allows a host job to initiate processing at any time, define file transfer rules and direct PC activity between transfers. It is assumed that the reader of this manual has a good working knowledge of mainframe operations and a basic understanding of Windows PC operating systems.

About this Manual

This manual provides detailed instructions for installing, configuring and running pcMAINFRAME Express on your host mainframe and target PCs. It includes JCL samples of typical transfer functions to enable you to get started quickly. This manual is organized as follows: Chapter 1 - Introduction, provides an overview of processing and summarizes the major components and system requirements for both the mainframe and PC. Chapter 2 -Mainframe Installation, describes procedures for mainframe installation and verification.. Chapter 3 - Mainframe Processing, explains how to use pcMAINFRAME Express to define and control transfers with a mainframe job. It includes JCL samples, which can be used for modeling your transfer. Chapter 4 - PC Installation, describes procedures for installing pcMAINFRAME Express and APPX TPN Services on the PC. Chapter 5 - PC User Guide, explains how to use pcMAINFRAME Express and its support applications on the PC. It provides detailed instructions on how to maintain setup files, configure and manage the APPX TPN service and run PCXPRESS.

pcMAINFRAME Express

Chapter 1 - Introduction 1

Chapter 6 - Messages, lists the messages that are issued by pcMAINFRAME Express and explains each of them. Suggested actions are also listed where appropriate. Appendix A - Device Configuration for Commonly Used Devices describes some common communication environments and details configuration requirements and options. Appendix B - Translate Tables explains how to customize the translation of characters between ASCII on the PC and EBCDIC on the mainframe.

__________________________________ cfSOFTWARE is committed to ensuring that pcMAINFRAME Express continues to be of value to you. We invite your comments, suggestions, insights and questions as you work with pcMAINFRAME Express. Our technical support number is (847) 824-7180. Visit us at our web site: www.cfsoftware.com

2 Chapter 1 - Introduction

pcMAINFRAME Express

Overview
pcMAINFRAME Express is a reliable, fast, and easy-to-use application that provides host control of file transfers between IBM mainframes and Windows PCs. It is capable of operating with a variety of communications options including LU2, TN3270, TCP/IP and LU6.2. The communications programs on the mainframe and the PC were designed to work with each other in a cooperative processing environment. This means that they each possess intelligence and work together to accomplish the functions of data transfer. These functions include a proprietary communication protocol, data compression, error checking and error correction. Both the PC and the mainframe programs have specific portions of the work to perform. Each program does the portion of the processing to which it is best suited and communicates with the other program to accomplish the entire task. The mainframe programs are responsible for data access, recording activity, process control and mainframe communications. The PC programs are responsible for the user interface, options and communications configuration, data management on the PC, and communications from the PC end.

Host Mainframe

Batch Job
- Initiates - Transfers - Controls

Client PC

Figure 1-1: pcMAINFRAME Express Control flow

pcMAINFRAME Express

Chapter 1 - Introduction 3

Component Summary
The mainframe and PC portions each consist of several related programs. The following is a summary of the major components and a brief description of the program functions and relationship with other programs.

Mainframe components
CFXPRESS - is the primary transfer application on the mainframe. It validates and processes the command file that controls the transfer process. This program is responsible for communications, transfer protocols and mainframe file I/O. CFXCMPXA - is the advanced compression handler. This module is responsible for compressing and decompressing data into the communication buffers during transfer processing.

PC components
PCXPRESS.EXE - is the primary transfer application on the PC. It runs unattended, waiting for the host to initiate a session. After initiation, it is responsible for processing transfers and executing any PCSCRIPT sent by the mainframe. After each session, the application returns to the WAIT state until another request is received from the host. PCXSETUP.EXE - creates, displays and updates setup files. The setup file is required when running PCXPRESS and contains information about the communication device used, various run-time processing parameters and optional Dialog scripts to run before and after each transfer session. DIALOGG.EXE - processes dialog scripts used to automate 3270 functions. It can be used as a terminal emulator or to run a script command file. Scripts can be used to automate such functions as navigating through VM and VTAM, launching PC applications or performing PC file maintenance (copy, move, rename and delete). MAINCON.EXE - sets any required communications configuration options. MAINCON creates specific configuration files (MAINCFG.xxx) that are used during communications. MAINXLAT.EXE - used to create/modify customized text translate tables.

APPX TPN Service (TCP/IP Listener)

These modules are used to provide support for transfers using direct TCP/IP. TCP/IP for VSE or TCP/IP for MVS are required for this type of connection. APPXTPNS.EXE - the core TPN Service program. APPXTEVT.EXE - displays the TPNS Event Log, which provides a trail of all activity that has filtered through the TPN Service. This program is not used under NT; there, the NT Event Viewer is used instead. APPXTCFG.EXE - is the APPX TPN Service configuration program. APPXTMGR.EXE - is the APPX TPN Service Manager. This is used to stop, start and view the status of the TPN Service.

4 Chapter 1 - Introduction

pcMAINFRAME Express

System Requirements
Mainframe Environment
Operating System: DOS/VSE, VSE/ESA, MVS, MVS/ESA or OS/390. VTAM: VTAM (v3.2) is required COBOL: VS COBOL II, release four or compatible run time libraries. TCP/IP: Direct TCP/IP connections require TCP/IP for VSE or TCP/IP for MVS.

PC Environment
Operating System: Microsoft Win95, Win98, Win/NT (v4.0 or above) or Windows 2000. Computer: an IBM PC or fully compatible machine. Disk: at least 1 hard drive with a minimum of 10 megabytes of available storage. Local Area Network disks are also supported. Communication: one or more of the following: Direct TCP/IP: Direct TCP/IP connections are supported with TCP/IP for VSE or TCP/IP for MVS. TCP/IP with TN3270: Most TCP/IP stacks available for Windows processors are supported. Supports IBMs TCP/IP for MVS, VM, and VSE, as well as SNA gateways with TN3270 server support. 3270 Terminal Emulators: Most 3270 terminal emulation products are supported. Gateway: compatible networks are supported through a variety of gateway devices. LU6.2: a device connected to the host with an LU6.2 connection. Terminal Emulator Board: with a coaxial cable connecting to an IBM Type A Device Adapter Port.

pcMAINFRAME Express

Chapter 1 - Introduction 5

6 Chapter 1 - Introduction

pcMAINFRAME Express

Chapter 2 - Mainframe Installation

Installation Checklist
The following steps are needed to install pcMAINFRAME Express on your mainframe. Each step is explained in detail later in this chapter. 1. 2. 3. 4. Restore distribution tape library(s) to a new or existing library. Modify VTAM definitions. Not required for direct TCP/IP connections. Review and modify sample JCL to run file transfers. Verify Installation - Run a transfer.

VSE Library Restore

The distribution tape contains core image and source statement libraries in standard LIBR BACKUP format. Use the librarian program LIBR to add the pcMAINFRAME Express program and source members to your library, as shown in Figure 2-1: VSE Restore JCL.
// JOB RESTORE PCMAINFRAME EXPRESS MODULES //ASSGN SYS006,TAPE DISTRIBUTION TAPE //PAUSE MOUNT DISTRIBUTION TAPE ON SYS006 //MTC REW,SYS006 REWIND DISTRIBUTION TAPE //EXEC LIBR RESTORE CFSOFT.DISTEXP.*.*:library.sublib TAPE=SYS006 LIST=YES REPLACE=YES /* // MTC RUN,SYS006 UNLOAD DISTRIBUTION TAPE /&

Figure 2-1: VSE Restore JCL

The restored library can be merged into an existing library or added to your search chain for program execution. Sample JCL for merging the CFXPRESS executable into an existing library is shown in Figure 2-2: VSE/SP Merge Library JCL.
// JOB MERGE VSE/SP LIBRARIES // EXEC LIBR CONNECT SUBLIB=library.sublib:your.lib COPY *.PHASE /*

Figure 2-2: VSE/SP Merge Library JCL

pcMAINFRAME Express

Chapter 2 - Mainframe Installation 7

MVS Library Restore

pcMAINFRAME Express is distributed as an IEBCOPY format tape of a load library and a source (CNTL) library. Use the IBM utility IEBCOPY to restore the two libraries to your system or add their contents to existing libraries. Figure 2-3 below is an example of IEBCOPY JCL that adds these members to new libraries.
//CFXINST JOB .......... //* ------COPY LOAD MODULES FROM TAPE - FILE 1 //STEP1 EXEC PGM=IEBCOPY //SYSPRINT DD SYSOUT=* //SYSUT1 DD DSN=CFX.LOAD,DISP=(OLD,PASS), // UNIT=TAPE,VOL=SER=CFX001,LABEL=(1,SL) //SYSUT2 DD DSN=CFX.LOADLIB.LOAD,DISP=(NEW,CATLG), // UNIT=DISK,VOL=SER=VOLSERX, // SPACE=(TRK,(80,5,20)), // DCB=(BLKSIZE=6144,RECFM=U) //SYSIN DD * C I=((SYSUT1,R)),O=SYSUT2 //* ----COPY SOURCE MODULES FROM TAPE - FILE 2 //STEP2 EXEC PGM=IEBCOPY //SYSPRINT DD SYSOUT=* //SYSUT1 DD DSN=CFX.SOURCE,DISP=(OLD), // UNIT=TAPE,VOL=SER=CFX001,LABEL=(2,SL) //SYSUT2 DD DSN=CFXPRESS.SOURCE.CNTL,DISP=(NEW,CATLG), // UNIT=DISK,VOL=SER=VOLSERX, // SPACE=(TRK,(10,2,10), // DCB=(LRECL=80,BLKSIZE=8000,RECFM=FB) //SYSIN DD * C I=((SYSUT1,R)),O=SYSUT2

Figure 2-3: IEBCOPY JCL

VTAM Definitions - LU2, LU6.2 and TN3270

Note. VTAM definitions are not required for direct TCP/IP connections. pcMAINFRAME Express uses VTAM to acquire the PC terminal used during Express file transfers. To run pcMAINFRAME Express, you must add one or more APPL definitions to your VTAM tables. The number is dependent on the number of concurrent sessions you wish to run. There must be one APPLID defined for each concurrent session. These definitions may be added to an existing application major node or placed in a separate major node. It may be simpler to create a new major node so that you can modify and activate it independently from other applications.

APPL IDs
Each concurrently running copy of CFXPRESS requires a unique VTAM APPL. This APPL is specified in the APPLID parameter of the CONNECT statement. CFXPRESS can use a pool of APPLs, and can select any free APPL in that pool. The name of the first APPL is specified in the APPLID parameter. If that APPL is in use CFXPRESS will increment the APPL until it encounters an available APPL or encounters an invalid APPL name. The names of the APPLs are formed by overlaying the end of the APPL specified in APPLID with a sequentially increasing number (starting at two). For example, if the first APPL is specified as HIFAP01, the second generated name will be HIFAP02. For simplicity, make the first APPL name in a pool end with 01 or 001. A sample VTAM definition follows below: VTMAPPL5 VBUILD TYPE=APPL HIFAP01 APPL AUTH=(PASS,ACQ),MODETAB=modetab[,APPC=YES] HIFAP02 APPL AUTH=(PASS,ACQ),MODETAB=modetab[,APPC=YES] . . HIFAP09 APPL AUTH=(PASS,ACQ),MODETAB=modetab[,APPC=YES] HIFAP10 APPL AUTH=(PASS,ACQ),MODETAB=modetab[,APPC=YES]

8 Chapter 2 - Mainframe Installation

pcMAINFRAME Express

This VTAM table defines a pool of ten APPLs for pcMAINFRAME Express. The MODETAB= parameter should reference the standard MODETAB for the installation. The APPLs for the installations CICSs make a good reference for any other parameters required for the installation. If security is established for the APPLs, either by using the PRTCT=pswrd parameter on the APPL statement or by an external security manager, the same password must be set for every APPL in a pool. If security is established, the required password must be supplied in the APPLPASS(pswrd) parameter of the CONNECT function when running the program CFXPRESS. If LU6.2 connections are to be used with CFXPRESS, APPC=YES must be coded on the APPLs. In addition, a VPACING value may be set. See Appendix A Configuration for Commonly used Devices, for additional information regarding LU6.2 connections.

Terminal LUs
CFXPRESS attempts to connect to a specific LU in order to transfer data to the PC attached to that LU. In general, CFXPRESS can connect to any LU that can be uniquely identified and accessed from the SNA domain in which CFXPRESS is running. The most significant restriction is that the PC be uniquely identifiable and available to do the data transfer. If the PC is not running, is not connected to the SNA network, or is not running the correct software, data transfer will not be possible. Two particular types of PC connections present identification problems: Pooled LUs in SNA/LAN gateways, and dial-up LU pools (the VM DIAL command, SDLC dial-up facilities and similar connections). These are two versions of the same problem: the PC does not have a permanently assigned LU name. In all of these cases, the SNA network is set up with a pool of LUs, and when a PC connects to the SNA network, it is assigned an available (but otherwise arbitrary) LU in the pool. In the case of SNA/LAN gateways, it is usually possible to define a specific LU for a given PCs use. This LU name will have to be coordinated with both the VTAM/NCP systems programmer and the SNA/LAN gateway administrator. The VM DIAL command presents a special problem for non-SNA terminals that are not owned by VTAM; until the user at the terminal enters a DIAL command to connect to a VTAM, the terminal is not visible to the SNA network at all. By default, the VM DIAL command will attach the terminal to the first available SPECIAL 3270 device address for the guest machine. These device addresses are assigned LU names by the VTAM running in the guest machine, but VM treats the list of addresses as a pool unless a specific address is specified on the DIAL command. If a device address is assigned for a particular PCs use, this will have to be coordinated with the systems programmer for the guest machine as well as the VTAM systems programmer and the VM systems programmer. For SDLC dial-up connections it is possible to assign each PC a specific PU ID (also called XCHG ID), so that the connecting PCs will have unique LU names. TCP/IP TELNET TN3270 connections have the same problem in that there is no way to determine to which LU a TN3270 session will attach. If the TN3270 server supports TN3270E, a specific LU can be asked for when establishing the connection to the host. See the 3270 configuration section for additional information on configuring the TN3270 drivers to request a specific LU. Terminal session managers also interfere with SNAs management of LUs. A terminal connected to a session manager is in a session and cannot be acquired by

pcMAINFRAME Express

Chapter 2 - Mainframe Installation 9

CFXPRESS. The sessions created by the session manager typically are assigned dynamically and thus cannot be identified ahead of time for use by CFXPRESS. With any of these connections, it is likely that the PC is not connected to the SNA network at all times. In any case where an intermittent connection is used, some form of coordination with the PC will be required to insure that the PC is available when CFXPRESS is ready to run.

LU6.2 Connections
LU6.2 connections are usually not subject to the pool problem that terminal LUs are, but the situation can be created with some gateways. In that case, a specific LU should be assigned to the PC on which the CFXPRESS started transfer will run.

Multiple Domain SNA Networks

Several new cross-domain definitions may be required if CFXPRESS is to manage terminals and APPLs belonging to different domains. These definitions are not specific to CFXPRESS, but may not be defined in an installation because there may never have been a need to acquire particular resources from certain locations before. In most installations, the various cross-domain definitions will already be set up. If the terminal LU is owned by a different domain (a different SSCP, for example), an appropriate CDRM and CDRSC (or an ADJSSCP) must be specified or the terminal cannot be acquired by CFXPRESS.

JCL Samples
The pcMAINFRAME Express source library contains JCL samples of typical transfer requests that may be modified to suit your needs. These samples can be reviewed and made available as models for users of CFXPRESS. A brief description of each example is included below. A complete listing of each member is included in Chapter 3 - Mainframe Processing.

XPVERIFY
This member is a basic download that can be used to verify that the mainframe and PC installations are correct. The Installation Verification section at the end of this chapter details the steps necessary to modify and run this job.

XPUPLOAD
This member runs an initial PCSCRIPT that checks for the existence of a file on the PC, and if there, it uploads the file. After a successful upload, the PC file is deleted.

XPDNLOAD
This member downloads a file to the PC, runs a PCSCRIPT that copies the file to a new directory with a date specific file name, then notifies the PC user that the file has arrived.

10 Chapter 2 - Mainframe Installation

pcMAINFRAME Express

XPDNEXEC
This member downloads a file to the PC, then runs a PC script that runs an external process that dials out to a client site and receives one or more transaction files; reads a status file produced during the above process; if status is OK, uploads the received data files; if status is not OK, sets a return code for the mainframe job.

Installation Verification
The installation of pcMAINFRAME Express can be verified by readying PCXPRESS on a target PC, then submitting a host job to initiate and execute a download. See Chapter 5 - PC User Guide, for detailed instructions on getting the target PC ready for transfers. Depending on the type of connection, the following information must be defined to the host job in the CONNECT section. LU2 (3270 and TN3270) The LU name of the 3270 terminal to connect to. The name of the SNA APPL to be used (e.g. HIFAP01). Note. For this type of connection, the PC must be connected to the VTAM USS screen, as the host asks VTAM for a connection to the specified LU. Direct TCP/IP TCP/IP connection mode. The DNS name or IP address of the PC to connect to. LU6.2 LU6.2 connection mode indicator. The LU name of the LU6.2 stack on the PC to connect to. The name of the SNA APPL to be used (e.g. HIFAP01). The LU6.2 logmode (defaults to #INTER if not specified). Sample JCL for the mainframe job is provided below. The job is setup to do a download of a sequential file. The JCL should be reviewed and modified to run in your shop. Choose the CONNECT statements that are appropriate for your connection type.

pcMAINFRAME Express

Chapter 2 - Mainframe Installation 11

XPVERIFY for VSE

* $$ JOB JNM=XPVERIFY,CLASS=A // review * $$ LST CLASS=U,DEST=(*,ANY) // JOB XPVERIFY - PCM EXPRESS DONWLOAD /* --------------------------------------------------------------* /* PCMEXPRESS - INSTALLATION VERIFICATION /* /* DOWNLOAD ANY SEQUENTIAL FILE /* --------------------------------------------------------------* // LIBDEF *,SEARCH=library.sublib // modify // ASSGN SYS081,SYSLST /* JCL FOR SEQUENTIAL DISK INPUT // DLBL SEQDAT1,CFSOFT.TEST.EXPRDAT1,0 // modify // EXTENT SYS031,SYSWK1,1,0,799968,20000 // modify // ASSGN SYS031,DISK,VOL=SYSWK1,SHR // modify /* // EXEC CFXPRESS CONNECT // 3270 connection LUNAME(LUID) // modify APPLID(HIFAP01) // review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONNECT // TCP/IP connection TCPIP(YES) HOST(tcp.ip.address) // modify PORT(2500) // review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONNECT // LU6.2 connection LU62(YES) LUNAME(SLU-NAME) // modify APPLID(HIFAP01) // review DOWNLOAD DEV(DISK) DDNAME(SEQDAT1) SYSNUM(031) BLOCKSIZE(MAX) RECORDSIZE(550) RECORDFORMAT(VB) PCFILE(C:\PCM_EXP\XPVERIFY.D1) /* /& * $$ EOJ

// modify // review

Figure 2-4: Sample JCL for VSE Installation verification

The lines marked modify or review may need to be changed. LIBDEF Change the search library to the name of the library in which CFXPRESS was installed. DLBL/EXTENT/ASSGN Define a sequential data set for transfer. CONNECT statements: LUNAME(LUID) - Change to the LU name of the terminal that VTAM should attach to. APPLID If the suggested VTAM APPLIDs were not used, change to match the installed APPLID. HOST - Insert the TCP/IP address of the PC to connect to. LUNAME(SLU-NAME) - Change to the LU name assigned to the PC running the LU6.2 stack.

PCFILE Change if a different path or PC file name is desired. BLOCKSIZE / RECORDSIZE / RECORDFORMAT Change these fields to match the characteristics of the file being downloaded.

12 Chapter 2 - Mainframe Installation

pcMAINFRAME Express

XPVERIFY for MVS

//A0370CF1 JOB (0370,0100),C+F,MSGCLASS=X // modify /* --------------------------------------------------------------* /* PCMEXPRESS - INSTALLATION VERIFICATION /* /* DOWNLOAD ANY SEQUENTIAL FILE /* --------------------------------------------------------------* //JOBLIB DD DSN=PCMXPRESS.PROD.LOADLIB,DISP=SHR // modify /* //XPVER01 EXEC PGM=CFXPRESS //REPORT DD SYSOUT=* //SEQDAT1 DD DSN=PCMFTEST.SEQ.DATA,DISP=SHR // modify //INPUT DD * CONNECT // 3270 connection LUNAME(LUID) // modify APPLID(HIFAP01) // review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONNECT // TCP/IP connection TCPIP(YES) HOST(tcp.ip.address) // modify PORT(2500) // review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONNECT // LU6.2 connection LU62(YES) LUNAME(SLU-NAME) // modify APPLID(HIFAP01) // review DOWNLOAD DEV(DISK) DDNAME(SEQDAT1) PCFILE(C:\PCM_EXP\XPVERIFY.D1) /* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //

// review

Figure 2-5: Sample JCL for MVS Installation verification

The lines marked modify or review may need to be changed. JOB Change to your shop standards for a //JOB statement. JOBLIB Change the search library to the name of the library in which CFXPRESS was installed. SEQDAT1 Change DSN to any sequential data set for transfer. CONNECT statements: LUNAME(LUID) - Change to the LU name of the terminal that VTAM should attach to. APPLID If the suggested VTAM APPLIDs were not used, change to match the installed APPLID. HOST - Insert the TCP/IP address of the PC to connect to. LUNAME(SLU-NAME) - Change to the LU name assigned to the PC running the LU6.2 stack. PCFILE Change if a different path or PC file name is desired.

Submit the Transfer

Before the job is submitted, the pcMAINFRAME Express must be installed and configured on the target PC. Please see Chapter 5 - for PC instructions on how to configure and ready the PC for transfers

pcMAINFRAME Express

Chapter 2 - Mainframe Installation 13

14 Chapter 2 - Mainframe Installation

pcMAINFRAME Express

Chapter 3 - Mainframe Processing

Overview
A pcMAINFRAME Express transfer session is started from a batch job running in VSE or MVS. The initiating job has complete control over the transfer definition parameters. Data file uploads and downloads are initiated from the mainframe. Fixed, ASCII and binary (transparent) data formats are supported. Sequential tape, sequential disk, VSAM , PDS and managed SAM file formats can be transferred. A transfer is controlled with statements coded in a command file. The command file includes CONNECT statements (to define the connection to the PC), UPLOAD/ DOWNLOAD statements (to define file transfers), and PCSCRIPT statements (to control processing on the PC). Return codes can be tested to control execution of command sets or subsequent job step processing. The PC must be ready to receive a transfer from the host. For LU2 connections, PCXPRESS must be running on the PC with an active connection to a VTAM session. For LU6.2 and direct TCP/IP connections, the PC application will be automatically started once the connection is established

File Transfer Considerations

Record Lengths
When uploading to variable length files, the length of the records written will be the length of the PC file record. Records in fixed format files will be truncated or padded to the specified record size. The default PAD character is spaces; nulls (binary zeros) will be used if the PAD(NULL) parameter is coded. When uploading to a VSAM file, the RECORDSIZE(nnn) parameter will force a write for the record length specified. Downloaded records will be written with the length of the mainframe record and be delimited with a CR/LF. ASCII format processing will truncate trailing spaces before writing to the PC. To read or write PC file records without a CR/LF delimiter, the PCRECSZ(nnn) parameter must be used.

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 15

KSDS VSAM Upload Considerations

pcMAINFRAME Express uses key processing for KSDS uploads. The entire key must be uploaded. If a record with a matching key exists on the file, the uploaded record will replace it.

Data Compression
pcMAINFRAME Express uses a Lempel-Zev compression algorithm to optimize transfer rates. The dictionary size is controlled with the DCOPTION/UCOPTION parameters.

VTAM Considerations
The information necessary to define the host initiation and transfer facility to VTAM is contained in Chapter 2 -Mainframe Installation. Refer to that chapter for detailed information.

LU6.2 Usage notes

Your SNA server and VTAM must be configured to support the LU6.2 connection that the host will make to the PC(s). Appendix A - Configuration for Commonly used Devices contains details regarding configuration requirements for LU6.2 connections. Please contact your Network Administrator or Systems Programmer for further information on the LU6.2 configuration at your facility.

Audit Files
You can select one of three different formats to create an optional audit trail file. Fixed Format - creates a file with a single fixed record for each transfer or script processed. This type of audit file could be used to update a database or VSAM file to provide online query of transfer status. Basic Format - creates a file with the same data as fixed in comma delimited format. A basic format audit file could be downloaded to a PC, then added to a database to provide transfer status look-up to a centralized PC support group. Log Format - creates a file with a series of 80-byte log record in display format that details the results of each transfer or script processed. The Log format audit file is an easy to read transfer report that can be viewed directly on the mainframe or on a PC after download. When an audit file is specified, an AUDITID parameter can also be used to uniquely identify the Job in the audit file. This ID will be moved to the first field of EACH audit record.

16 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

Audit File Data

The following fields are defined in the fixed format audit record. Field Name AUDIT-ID LUNAME APPLID NUMBER RUN-TIMESTAMP START-TIMESTAMP END-TIMESTAMP FUNCTION PCFILE PROFILE MF-DDNAME RECORD-COUNT BYTE-COUNT COMPRESS-RATE COMPRESS-TYPE SPEED SKIPPED-SW RUN-SKIP-IND TEST-RC-IND TEST-CONDITION TEST-VALUE MAXRC LASTRC USERRC THISRC ERROR-LIT ERROR-MSG Unused Pos 1 13 21 29 32 51 70 89 97 203 211 219 228 239 242 244 253 254 255 256 258 262 266 270 274 278 285 365 Len 12 08 08 03 19 19 19 08 06 08 08 09 11 03 02 09 01 01 01 02 04 04 04 04 04 07 80 36 Data Type Char Char Char Num Char Char Char Char Char Char Char Num Num Num Char Num Char Char Char Char Num Num Num Num Num Char Char Char Value

yyyy-mm-dd-hh.mm.ss yyyy-mm-dd-hh.mm.ss yyyy-mm-dd-hh.mm.ss UPLOAD/DOWNLOAD/SCRIPT

99v9 (as %) (as Bytes per minute) Y=skipped R=runif S=skipif M=max L=last U=user EQ/GE/LE/NE/LE/LT/GT

WARNING/ERROR/MESSAGE

A sample COBOL copybook, PCMAUFCB.COB can be found in your source definition library. Sample DB2 table definition and load control statements can also be found in source code members PCMCRAUF.A and PCMLDAUF.A.

Transfer Control
The command file provides a great deal of flexibility for control of transfers and processing on the PC. The statements defined for an UPLOAD, DOWNLOAD or PCSCRIPT function are considered a process. Each process can test previously set return codes to determine its execution status.

PCSCRIPT Capabilities
Each PCSCRIPT process consists of dialog script statements that are downloaded and executed on the PC. A dialog is capable of performing many functions on the PC, such as file manipulation (find, read, write, copy, delete) program execution or launch, etc.

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 17

The pre-defined variables, &MAXRC, &LASTRC and &USERC, can be used to test the results of previously run processes. The QUIT(nnn) statement can be used to set a specific user return code for testing by any further process in the session. Sample scripts can be found in the JCL Examples section for both VSE and MVS.

Return Codes
An overall return code is set upon completion of the program. The return code can be set in one of two ways: 1. 2. As a normal result of program processing. Possible return codes are defined below. As the result of setting a &USERRC in a PC script. This feature gives you control over return code setting when transfer processing is conditional.

The following return codes define the values set during transfer or script processing by the application: 20 Unable to start processing. This error cannot be overridden. It is caused by errors such as syntax errors in the command set, a critical problem with the VTAM interface, a problem with the initial connection to the PC, or an open error on the Command or Transfer Report files. 16 Unable to continue processing. This error cannot be overridden. It is caused by a critical communications problem or a critical problem with the PC during processing. If the PC stops sending/accepting data, or if the communication link fails, this return code will be set. 12 One or more transfers failed. This error can be caused by a problem on either the PC or the Mainframe. File open errors, out-of-space conditions, invalid file names or directories will set this return code value. 8 One or more PC scripts failed to execute properly. This error is caused when an error occurs in a control script that is running on the PC. Syntax errors, runout or timeout errors, user BREAKS and other dialog errors will set this return code value. 4 User issued a QUIT during PCSCRIPT processing, and the QUIT value set was not 240 - 255. other Any RETURN CODE from 0 to 15 can be set during PC script process by issuing a QUIT(nnn) statement where nnn is between 240 and 255. This request will force the step return code value to 0 to 15 (nnn - 240) and will immediately end all further processing.

Return Code Testing

The return codes defined above can be tested before any TRANSFER is run, or during the processing of any PCSCRIPT. The test can be used to either RUN or SKIP the process if the condition is true. Three different Return Code values can be tested in this way: MAXRC - the highest non-user return code value set during processing. Note: this value will usually be 0, 4, 8 or 12 because both 16 and 20 force immediate termination of all processing.

18 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

LASTRC - the return code value set during execution of the last TRANSFER or SCRIPT process that ran. A skipped transfer has no effect on LASTRC. The LASTRC value set by a PCSCRIPT can be: 0 (OK) 4 (any QUIT) 8 (SCRIPT process error) USERRC - the QUIT(nnn) code value set during PCSCRIPT processing when the QUIT code set is between 33 and 239.

Note: if a QUIT(nnn) is issued with a value between 240 and 255, all processing ends and the program Return Code will be set to: 0 - 15 (nnn - 240). Examples of return code testing are shown in the examples found later in this chapter.

Command File
Command Syntax
All commands have this general structure:
FUNCTION parameter(s) terminator FUNCTION A function defines a specific action to be performed. The

command file can contain several functions and their associated parameters. The CONNECT function must be defined only once. Separate each function from its parameter(s) with one or more blanks.
parameter One or more keyword parameters follow the function.

Keyword parameters may be in any order following the verb. Some keyword parameters require values or names. In this case, the value or name must be enclosed in parenthesis. For example:
MEMBER(membername)

Separate all parameters with one or more spaces or commas. Continuing parameters Parameters may be continued over any number of lines, but if a parameter is split between lines the continuation character, -, must be the last character on the line. The following example requires a continuation character: UPLOAD PC FILE(c:\userdir\ datafile.dat) If a keyword parameter and/or its value is coded on new line, then a continuation is not required.
terminator indicates the end of a Function Set. It can be:

A new FUNCTION The end of the command file /END

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 19

Multiple Requests
Each function requests a different service. All function requests are read and validated before the attempt to connect to PC file is made. A function and all its parameters must be completely coded before the next function can be defined. The following defines number of times any function can be used in a single job. CONNECT UPLOAD/DOWNLOAD Once. Maximum 100; Requires one or more DDNAME or DLBL/ASSGN statements in the JCL. Maximum 100.

PCSCRIPT

Command File Format

CONNECT LU2 (3270) connections LUNAME(luname) APPLID(applid) [APPLCOUNT(nnn)] [APPLPASS(password)] LU62(YES) LUNAME(slu-name) APPLID(applid) [APPLCOUNT(nnn)] [APPLPASS(password)] [LOGMODE(logmode)] [LU62USER(ffpuser)] [LU62PASS(ffpswd)] [TPN(tpn)] TCPIP(YES) HOST(tcp.ip.address) PORT(port#) [SUBSYSID(subsys)] [TCPNAME(MVSregionName)] [TPN(tpn)] [RETRY(nnn[,zzz])] [NOTRACE|TRACE] [DCOPTION(xx)] [UCOPTION(xx)] [AUDIT(FIXED|BASIC|LOG)] [AUDITID(userdefined)]

LU6.2 connections

TCP/IP connections

ALL connections

20 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

DOWNLOAD|UPLOAD Data file transfers

[SKIPIF(RC,COND,nnn)] [RUNIF(RC,COND,nnn)] DDNAME(ddname) DEV(DISK|TAPE|ESDS|KSDS) PCFILE(pcfile) PCRECSZ(nnnnnn) [SYSNUM(nnn)] [BLOCKSIZE(nnnnn)|MAX] [RECORDSIZE(nnnnn)] [RECORDFORMAT(F|FB|V|VB)] [REPLACE|NOREPLACE|APPEND] [FIXED|ASCII|TRANSPARENT|NOXLATE] [MIXEDCASE|UPPERCASE|WORDPROCESS] [CTRLZ|NOCTRLZ] [PAD(SPACE|NULL)] Any valid script . /END

PCSCRIPT

Figure 3-1: Command File Format

Parameter Descriptions
Connect Parameters
CONNECT (define VTAM or TCP/IP connection parameters) APPLCOUNT(nnn) Optional. The number of APPLs in the pool of APPLs that CFXPRESS can use for connects. See the VTAM Considerations section for additional information on APPLCOUNT usage. APPLID(applid) Required. The name of the SNA APPL that CFXPRESS will use. See the VTAM Considerations section for additional information on APPLID. APPLPASS(password) Optional. Password for the APPLID if needed. AUDIT(NONE | FIXED | BASIC | LOG) Optional. Used to indicate the type of AUDIT file to be produced. If specified, a //CFAUDIT DD statement or //DLBL is required to define the audit file. AUDITID(userspecified) Optional. For audit files, this ID (up to 12 characters) will be inserted in the first field of each audit record produced. If not specified, this field will be null (BASIC) or spaces. DCOPTION(xx) and UCOPTION(xx) Optional. Used to specify one or more compression methods during data file download. DCOPTION(**) indicates that the compression option supplied by the PC should be used. For detailed information on advanced compression methods and their effect on memory allocation, see Chapter 4 - PC Installation and User Guide, Advanced Parms screen.

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 21

HOST(tcp.ip.address) Required for direct TCP/IP. The TCP/IP address or DNS name of the remote host (target PC). LOGMODE(logmode) Optional. For use with LU6.2 connections to define the session logmode. Standard and commonly defined logmodes for LU6.2 are #INTER or #BATCH. LU62(Y) Optional. LU6.2 session indicator. Required for LU6.2 connections. When the connection is made, the PCs transfer application will be automatically started. Note: LU6.2 transfers require additional configuration on both the PC and mainframe. See Appendix A - Configuration for Commonly used Devices, for detailed information on LU6.2 configuration. LU62PASS Optional. For use with LU6.2 connections. Needed only if the PC has LU6.2 security on. LU62USER Optional. For use with LU6.2 connections. Needed only if the PC has LU6.2 security on. LUNAME(luname) Required. The SNA name of the 3270 terminal (the PC) to which CFXPRESS will attempt to connect. For LU6.2 connections, this is the APPC/LU6.2 name assigned to the target PC that is running the LU6.2 stack. NOTRACE | TRACE Optional. Specifies that a trace of the VTAM connect activity be produced. This parameter should be used for troubleshooting only. A TRACE file must be defined in the JCL in which trace is turned on. PORT(nnnn) Required for direct TCP/IP. The TCP port number to which a transfer is directed. The target PC must have APPX TPN service running and configured to listen on the specified port number. RETRY(nnn[,zzz]) Optional. Number of times, (nnn), and intervals in seconds, (zzz) between attempts, to attempt the connection of the LUNAME if it is busy. If the interval is not specified, the default is 5 minutes. SUBSYSID(nn) Optional. VSE only. If running more than one TCP/IP for VSE, the two-character sub-system identifier to use for TCP/IP services. TCPIP(Y) Optional. TCP/IP connection session indicator. Required for TCP/IP connections. When the connection is made, the PCs transfer application will be automatically started. The target PC must have APPX TPN services running. TCPNAME(tcpname) Optional. MVS only. If running more than one TCP/IP for MVS, the Address Space Name to use for TCP/IP services. TPN(appname) Optional. The name of the transfer application to run on the PC. Only used when multiple TPNs are defined on the target PC. The default TPN is CFXPRESS.

22 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

File Transfer Parameters

DOWNLOAD | UPLOAD SKIPIF(MAXRC | LASTRC | USERRC , NE | GE | GT | EQ | LE | LT , nnn) Optional. This parameter may be used to conditionally skip the transfer defined in this process. For example, the statement SKIPIF(MAXRC,GT,4) would cause the transfer to be bypassed if any prior processes returned a value greater than 4. RUNIF(MAXRC | LASTRC | USERRC , NE | GE | GT | EQ | LE | LT , nnn) Optional. This parameter may be used to run the transfer defined in this process ONLY if the condition is true. Note: A SKIPIF statement takes precedence over a RUNIF statement if both are defined in the same process. The RUNIF is effectively ignored. DDNAME - Optional. For MVS, specifies the DDNAME of the file to be transferred. For VSE, the DLBL name of the file to be transferred. If not specified, pcMAINFRAME Express uses the default as defined in the JCL requirements section that follows. SYSNUM(nnn) For VSE ONLY. The logical unit number (SYSnnn) used in the extent statement for the file to be transferred. The defaults are SYS020 for TAPE and SYS030 for DISK. DEV(DISK | TAPE | ESDS | KSDS) The data file device type. If not specified, the default is DISK. VSE Note: managed SAM files must be defined as ESDS. BLOCKSIZE(nnnnn)|MAX For VSE ONLY. Required for device type tape or disk and record format FB or VB. For FB, must be a multiple of recordsize or MAX. RECORDSIZE(nnnnn) For VSE ONLY. Required for device type tape or disk. For V or VB files, the record size must include the four-byte record descriptor word (RDW). RECORDFORMAT(F | FB | V | VB) For VSE ONLY. Required for device type tape or disk. PCFILE(Drive:\Path\Filename) Required. The name of the PC file to be written. A full path can be specified. Maximum length is 255 bytes. PCRECSZ(nnnnn) Optional. The PC record size where a CR/LF is not present or not to be written. When this parameter is used, no CRLF will be written on downloads and none will be required on uploads. Records of the size specified will be transferred. On upload, the last record will be padded with spaces or low-values if required. Any CRLF in the record is treated as data unless it occurs at the end of the defined PC record size. Transparent format files are read and written with the specified size records. REPLACE | NOREPLACE | APPEND Optional. Specifies the action to take if the file already exists on the PC. The default action is REPLACE.

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 23

FIXED | ASCII | TRANSPARENT | NOXLATE Optional. Defines the PC file data type. FIXED - The entire record will be transferred to the PC. EBCDIC to ASCII conversion will take place and a CR/LF delimiter will be written at the end of each record. ASCII - Trailing spaces will be removed from each record. EBCDIC to ASCII conversion will take place and a CR/LF delimiter will be written at the end of each record. TRANSPARENT - A binary transfer. The data will be transferred without any translation. No record delimiters are written. NOXLATE - On download, the entire record will be transferred to the PC with no data conversion. A CR/LF delimiter will be written at the end of each record. On upload, each record, as delimited by a CRLF, will be transferred to the mainframe. Data will not be translated and the record will be written with a length appropriated to the files LRECL and RECFM characteristics; records in fixed length files will be padded or truncated; records in variable length files will be written as received. Note: the CRLF will not be treated as data. MIXEDCASE | UPPERCASE | WORDPROCESS Optional. Defines the text mode for non-transparent transfers. MIXEDCASE - All valid text mode characters, including lower case letters will be transferred. Any non-text characters (for example, binary zeros) will be converted to spaces. UPPERCASE - All valid text mode characters will be transferred. Lower case letters will be converted to upper case and any non-text character encountered will be converted to spaces. WORDPROCESS - All valid text mode characters will be transferred. Any non-text mode character encountered (for example, binary zeros) will be transferred with no conversion. Thus, a HEX00 on the mainframe will be a HEX00 on the PC. CTRLZ | NOCTRLZ Optional. Determines whether a CTRL-Z, HEX1A, will be written at the end of a PC file during download. Writing the CTRL-Z is the default. PAD(SPACE | NULL) Optional. Defines the PAD character. Padding occurs when uploading to a fixed length sequential file and the PC record is shorter than the fixed record length, or when uploading to a VSAM file and the RECORDSIZE(nnn) option is specified. If a pad character is not specified, SPACES will be used.

24 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

PC Script Statements
PC scripts are dialog scripts that will be sent to and run on the PC when they are encountered in the command file. The script can be used to find, copy, rename files, launch PC applications, and test return codes to control continued processing of the transfer session. The predefined variables, &MAXRC, &LASTRC and &USERRC can be tested at any time during script processing. See the Dialog Programmers Guide for detailed information on the Dialog control language. Sample scripts can also be found in the JCL Examples section for both VSE and MVS. PCSCRIPT Script Statements . . /END Note: the /END statement is required at the end of each PCSCRIPT section. It must begin in column 1 of the record.

Process Reporting
Two reports are produced with each job executed, the Control Report and the Transfer Report. Control Report the Control Report recaps the Command File control statements and reports on syntax errors, shows any override parameters in effect and displays connect startup messages. Transfer Report the Transfer Report details connect information and provides transfer statistics and status information for each function requested. This could be used as a permanent record of transactions and their results.

Sample Reports
01/14/2000 Version 2.10 pcMAINFRAME Express CONTROL REPORT PAGE 1

Control Statements CONNECT APPLID(HIFAP01) UCOPTION(A4) DCOPTION(A4) Override Parameters LUNAME(SYS40025) UPLOAD DEV(ESDS) DDNAME(PCMEFHI) PCFILE(H:\PCMFTEST\UPDATA\INITTST1.UP1) RECORDSIZE(60) DOWNLOAD DEV(ESDS) DDNAME(PCMEFHI) PCFILE(G:\PCM4\TEST\INITBLK1.DE1) UPLOAD DEVICE(ESDS) DDNAME(PCMEFHI) PCFILE(H:\PCMFTEST\UPDATA\INITBLK1.UP2) DOWNLOAD DEVI(ESDS) DDNAME(PCMEFHI) PCFILE(G:\PCM4\TEST\INITBLK1.DE2) Connect Messages PCH090: Establishing PC connection at 11:48:41 PCH089: Initiating APPX session. 11:48:51

Figure 3-2: Control Report

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 25

01/14/2000 Version 2.10 CONNECT INFORMATION: 1. UPLOAD LUID: SYS40025

pcMAINFRAME Express TRANSFER REPORT APPLID: HIFAP01

PAGE

PC FILE: MF FILE: STATISTICS: STATUS:

H:\PCMFTEST\UPDATA\INITTST1.UP1 PCMEFHI Start: 11:48:56 End: 11:49:13 Records: 1,200 Bytes: 50,500 Compression: 81.2% Speed: 178,230 cpm Never Skip RC: Max: 0 Last: 0 User: 0 Result: RC = 0 G:\PCM4\TEST\INITBLK1.DE1 PCMEFHI Start: 11:49:14 End: 11:49:30 Records: 1,200 Bytes: 1,200,000 Compression: 98.3% Speed: 4,500,000 cpm Never Skip RC: Max: 0 Last: 0 User: 0 Result: RC = 0 H:\PCMFTEST\UPDATA\INITBLK1.UP2 PCMEFHI Start: 11:49:31 End: 11:49:44 Records: 1,200 Bytes: 50,500 Compression: 68.3% Speed: 233,076 cpm Never Skip RC: Max: 0 Last: 0 User: 0 Result: RC = 0 G:\PCM4\TEST\INITBLK1.DE2 PCMEFHI Start: 11:49:45 End: 11:50:06 Records: 2,400 Bytes: 1,250,500 Compression: 96.4% Speed: 3,572,856 cpm Never Skip RC: Max: 0 Last: 0 User: 0 Result: RC = 0 G:\PCM4\TEST\INITBLK1.DE3 PCMEFHI Start: 11:50:07 End: 11:50:37 Records: 2,400 Bytes: 1,250,500 Compression: 94.6% Speed: 2,500,998 cpm Never Skip RC: Max: 0 Last: 0 User: 0 Result: RC = 0

2. DOWNLOAD PC FILE: MF FILE: STATISTICS: STATUS: 3. UPLOAD PC FILE: MF FILE: STATISTICS: STATUS:

4. DOWNLOAD PC FILE: MF FILE: STATISTICS: STATUS: 5. DOWNLOAD PC FILE: MF FILE: STATISTICS: STATUS:

Figure 3-3: Transfer Report

Program Execution
For LU2 type connections, PCXPRESS must be running on the target PC before a CFXPRESS job is submitted and the target LU should be available to VTAM (at a VTAM menu). For LU6.2 and TCP/IP direct connections, the target PC must be configured and ready to receive transfers.

Job Control Language Requirements

VSE JCL Requirements
File Type Command File Status Report Audit Report Disk Input Tape Input KSDS Input ESDS Input Disk Output Tape Output KSDS Output ESDS Output Trace (Optional) DLBL Default*
CFAUDIT DISKIN TAPEIN KSDSIN ESDSIN DISKOUT TAPEOUT KSDSOUT ESDSOUT SYSLST

Logical Unit #
SYSRDR SYSLST SYS035 SYS030** SYS020** SYS030** SYS020** SYS081

* Any DLBL name (VSE) or DDNAME (MVS) can be used for data transfers. If the default is not used, a DDNAME(...) parameter is required to define the file name. ** If the default LU number is not used, a SYSNUM(nnn) parameter is required to define the logical unit number.

26 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

MVS JCL Requirements

File Type
Command File Status Report Any Data File, In/Out Audit Report Trace (Optional)

Default DDNAME
INPUT (any fixed 80 byte file) REPORT CFXDATA* CFAUDIT*** TRCVTM1

*** Requires the following DCB characteristics: Audit Type RECFM LRECL
FIXED BASIC LOG FB VB FB 300 304 80

Overrides
Any CONNECT parameter can be overridden by coding PARM=KEYWORD(value) on the EXEC statement. Multiple keywords should be separated with a comma. For example: PARM=LUNAME(&LUID),RETRY(5)

JCL Examples
VSE Examples
Example 1 A simple jobstream that downloads a VSAM KSDS file and a sequential disk file. A fixed audit file is produced.
* $$ JOB JNM=INITBULK,CLASS=0 * $$ LST CLASS=U // JOB CFXPRESS SIMPLE TRANSFERS /* ----------------------------------------------------------------/* TWO INPUT FILES - KSDS AND SD FILE /* ----------------------------------------------------------------// LIBDEF *,SEARCH=CFXPRESS.UTIL /* ----------------------------------------------------------------// DLBL KSDSIN,CFXPRESS.KSDSFILE,,VSAM,CAT=IJSYSCT // DLBL SEQDISK,CFXPRESS.SEQDATA,0 // EXTENT SYS030,SYSWK1,1,0,513891,256 // ASSGN SYS030,DISK,VOL=USER01,SHR /* // DLBL CFAUDIT,PCM.AUDIT,O // EXTENT SYS035,SYSWK1,1,0,13260,1000 // ASSGN SYS035,DISK,VOL=SYSWK1,SHR // EXEC CFXPRESS CONNECT LUNAME(HCF01201) APPLID(HIFAPPL) AUDIT(FIXED) AUDITID(DAILY-ROSTER) * --------------------------------------- KSDS FILE TRANSFER -----DOWNLOAD DEV(KSDS) PCFILE(INITBLK1.KS1) * --------------------------------------- SD FILE TRANSFER -----DOWNLOAD DEV(DISK) DDNAME(SEQDISK) BLOCKSIZE(10000) RECORDSIZE(500) RECORDFORMAT(FB) PCFILE(INITBLK.SQ1) /* /& * $$ EOJ

Figure 3-4: Data File Download VSE

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 27

The following samples are more complex and demonstrate the power of PCSCRIPT statements. Example 2 - Runs a PCSCRIPT to verify the input files existence, uploads to the mainframe, then deletes the PC file.
* $$ JOB JNM=XPUPLOAD,CLASS=0 * $$ LST CLASS=U // JOB XPUPLOAD - PCMEXPRESS UPLOAD // SETPARM LUID=SYS40028 /* --------------------------------------------------------------* /* PCMEXPRESS - UPLOAD FILE IF AVAILABLE /* IF UPLOADED AND SUCCESSFUL, DELETE THE PC FILE /* --------------------------------------------------------------* // LIBDEF *,SEARCH=CFSOFT.TEST4 // ASSGN SYS081,SYSLST /* VSAM MANAGED SAM (IMPLICIT DEFINE) // DLBL UPDATA,CFXPRESS.TEST.SALES,0,VSAM,RECORDS=5000,RECSIZE=500, CAT=CFSCAT // EXTENT ,CFS001 /* // EXEC CFXPRESS,PARM=LUNAME(&LUID) CONNECT APPLID(HIFAPPL) PCSCRIPT OPTION LANGLEVEL(3) CHDIR C:\MARKET FILES IF EXIST MIDWEST.SALES.DAT GOTO GOT_FILE ;DOES FILE EXIST? :NOFILE QUIT ; NOFILE, (QUIT SETS LASTRC = 4) :GOT_FILE END ; FILE EXISTS, (END SETS LASTRC = 0) /END UPLOAD RUNIF(LASTRC,EQ,0) DEV(DISK) DDNAME(UPDATA) BLOCKSIZE(MAX) RECORDSIZE(500) RECORDFORMAT(FB) PCFILE(MIDWEST.SALES.DAT) PCSCRIPT OPTION LANGLEVEL(3) IF NUM &LASTRC NE 0 GOTO NO_DELETE ; EVERYTHING OK? ON ERROR GOTO NO_DELETE DELETEFILE MIDWEST.SALES.DAT END :NO_DELETE QUIT ; NOFILE, (QUIT SETS LASTRC = 4) /END /& * $$ EOJ

Figure 3-5: Upload if PC file is available, then delete PC file

Example 3 - Downloads a file, copies it, adding the current date to its name, then notifies the PC user that the file was downloaded successfully.
* $$ JOB JNM=XPDNLOAD,CLASS=0 * $$ LST CLASS=U // JOB XPDNLOAD - PCM EXPRESS DOWNLOAD // SETPARM LUID=SYS40028 /* --------------------------------------------------------------* /* PCMEXPRESS - DOWNLOAD A FILE, /* COPY WITH DATE AND NOTIFY USER /* --------------------------------------------------------------* // LIBDEF *,SEARCH=CFXPRESS.LIB // ASSGN SYS081,SYSLST /* VSAM ESDS DOWNLOAD // DLBL ESDSIN,CFXPRESS.ESDS.STATS,,VSAM,BUFND=6,CAT=CFSCAT /* // EXEC CFXPRESS,PARM=LUNAME(&LUID) CONNECT APPLID(HIFAPPL) DOWNLOAD DEV(ESDS) PCFILE(C:\PCM_EXP\STATS.DAT)

28 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

* PCSCRIPT OPTION LANGLEVEL(3) IF NUM &LASTRC NE 0 GOTO NO_GO ; EVERYTHING OK? :SETUP ON ERROR GOTO NO_GO SET #FD1 = @SUBSTR(@DATE, 1, 2) ; GET MMDD FOR FILENAME SET #FD2 = @SUBSTR(@DATE, 4, 2) SET #mmdd = #fd1 #fd2 :COPY1 CHDIR C:\MARKET FILES ; GO TO MARKET DIRECTORY SET #FNAME = @STRCAT(MIDWEST.STATS., #MMDD, .DAT) COPYFILE C:\PCM_EXP\STATS.DAT TO @STRCAT(\PCM_WIN\STATS.DAT, #FNAME) :NOTIFY1 ;NOTIFY USER TIMEOUT(30) ON TIMEOUT GOTO NO_USER ;IF NO RESPONSE, JUST LEAVE DLGBOX NEW DLGBOX line1=Midwest Market File DLGBOX line2=@STRCAT(for: , #mmdd, Downloaded) DLGBOX button1=OK DLGBOX EXECUTE :NO_USER ;IF NO RESPONSE OR OK END :NO_GO ;IF UNABLE TO COPY QUIT(33) /END /* /& * $$ EOJ

Figure 3-6: Download a file, with copyfile and notification procedures

Example 4 - Downloads a file, runs an external process to send/receive data from client sites, checks the status of this external process, then uploads any transaction file(s) that were received from clients.
* $$ JOB JNM=XPDNEXEC,CLASS=0 * $$ LST CLASS=U // JOB XPDNEXEC - PCM EXPRESS DOWNLOAD AND RUN // SETPARM LUID=SYS40028 /* --------------------------------------------------------------* /* PCMEXPRESS - DOWNLOAD A FILE, /* RUN AN EXTERNAL PROCESS TO SEND PRICES TO CLIENT /* RECEIVE ORDERS /* CHECK STATUS OF SEND/RECEIVE /* UPLOAD TRANSACTION FILE /* --------------------------------------------------------------* // LIBDEF *,SEARCH=CFXPRESS.LIB /* VSAM KSDS DOWNLOAD // DLBL KSDSIN,CFXPRESS.KSDS.PRICE,,VSAM,BUFND=6,CAT=CFSCAT /* VSAM ESDS UPLOAD // DLBL ESDSOUT,CFXPRESS.ESDS.ORDER,,VSAM,BUFND=6,CAT=CFSCAT /* // EXEC CFXPRESS,PARM=LUNAME(&LUID) CONNECT APPLID(HIFAPPL) DOWNLOAD DEV(KSDS) PCFILE(C:\MARKET FILES\MIDWEST.PRICE.DAT) * PCSCRIPT OPTION LANGLEVEL(3) IF NUM &LASTRC NE 0 GOTO NO_GO ; EVERYTHING OK? * :SEND_RECV ;RUN THE EXTERNAL SEND/RECEIVE PROCESS CHDIR C:\PCPLUS RUN C:\PCPLUS\PCPLUS /FC:\PCPLUS\DIALSITE.ASP * ;CHECK RETURN SET IN PRIOR PROCESS * ;RECORD IS: NN1,NN2 (NN1=RC, NN2=COUNT) ON FILE_ERROR GOTO BAD_DIAL1 ON END_OF_FILE GOTO BAD_DIAL1 * OPEN (1) DIALSITE.RC READ READ (1) NUM #RC, #FCOUNT CLOSE (1) IF NUM #RC > 0 GOTO BAD_DIAL * :SET_FILES * SET #FD1 = @SUBSTR(@DATE, 1, 2) ; GET MMDD FOR FILENAME SET #FD2 = @SUBSTR(@DATE, 4, 2)

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 29

SET #MMDD = #FD1 #FD2 CALC #SEQ = 0 CALC #QUITRC = 33 + #FCOUNT ; SET RC FOR QUIT * :LOOP_COPY ; COPY FILES FOR UPLOAD CALC #SEQ = #SEQ + 1 IF NUM #SEQ > #FCOUNT THEN GOTO END_COPY ENDIF * ------------------------------------------------------------------* COPY FILES TO UPLOAD DIRECTORY, DELETE OLD! * ;OLD NAME, EG: ORDER1.DAT * ORDER2.DAT * ;NEW NAME, EG: SITE1.ORDER1.DAT * SITE1.ORDER2.DAT * ------------------------------------------------------------------SET OFILE = @STRCAT(C:\PCPLUS\ORDER, #SEQ, .DAT) SET NFILE = @STRCAT(C:\MARKET FILES\SITE1.ORDER, #SEQ, .DAT) COPYFILE #OFILE TO #NFILE DELETEFILE #OFILE GOTO LOOP_COPY * :END_COPY QUIT(#QUITRC) ;SET USERRC = 33 + NUMBER OF FILES TO Upload * ------------------------------------------------------------------:BAD_DIAL QUIT(255) ;SET JOB RC TO 15, NO FURTHER PROCESSING :BAD_DIAL1 QUIT(254) ;SET JOB RC TO 14, NO FURTHER PROCESSING :NO_GO QUIT(253) ;SET JOB RC TO 13, NO FURTHER PROCESSING /END * UPLOAD RUNIF(USERRC,GT,33) DEV(ESDS) PCFILE(C:\MARKET FILES\SITE1.ORDER1.DAT) UPLOAD RUNIF(USERRC,GT,34) DEV(ESDS) PCFILE(C:\MARKET FILES\SITE1.ORDER2.DAT) UPLOAD RUNIF(USERRC,GT,35) DEV(ESDS) PCFILE(C:\MARKET FILES\SITE1.ORDER3.DAT) UPLOAD RUNIF(USERRC,GT,36) DEV(ESDS) PCFILE(C:\MARKET FILES\SITE1.ORDER4.DAT) /* /& * $$ EOJ

Figure 3-7: Download a file, run external process, then upload transaction files.

MVS Examples
Example 1 A simple jobstream that downloads a VSAM KSDS file and a sequential disk file. This will produce a fixed audit file.
//JOBNAME JOB (acct) //* //* DATA FILE TRANSFER #1 //* 3 input files - sequential, KSDS, ESDS //* #1 - TAKE DEFAULT DDNAME (CFXDATA) //* #2 - TAKE DEFALUT DEV (DATA2) //* //JOBLIB DD DSN=CFXPRESS.LOADLIB,DISP=SHR //* //STEP1 EXEC PGM=CFXPRESS //REPORT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //CFAUDIT DD DSN=PCM.TEST.AUDIT,DISP=(,CATLG), // UNIT=SYSDA,SPACE-(TRK,(50,10),RLSE), // DCB=(LRECL=400,BLKSIZE=10000,RECFM=FB) //CFXDATA DD DSN=CFXPRESS.TEST.INFILE(TESTDATA),DISP=SHR //DATA2 DD DSN=CFXPRESS.TEST.CFXKSDS,DISP=SHR //DATA3 DD DSN=CFXPRESS.TEST.CFXESDS,DISP=SHR //INPUT DD * CONNECT LUNAME(HCF01200)

30 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

APPLID(HIF0001) DOWNLOAD PCFILE(INITBLK1.SD1) DOWNLOAD DDNAME(DATA2) DEV(KSDS) PCFILE(INITBLK1.KS1) UPLOAD DDNAME(DATA3) DEV(ESDS) PCFILE(INITBLK1.ES1) /* //

Figure 3-8: Data file Download MVS

The following samples are more complex and demonstrate the power of PCSCRIPT statements. Example 2 - Runs a PCSCRIPT to verify the input files existence, uploads to the mainframe, then deletes the PC file.

//XPUPLOAD JOB (ACCT) /* --------------------------------------------------------------* /* PCMEXPRESS - UPLOAD FILE IF AVAILABLE /* IF UPLOADED AND SUCCESSFUL, DELETE THE PC FILE /* --------------------------------------------------------------* //JOBLIB DD DSN=CFXPRESS.LOADLIB /* //XPUPDL1 EXEC PGM=CFXPRESS,PARM=LUNAME(CF32701) //REPORT DD SYSOUT=* //CFXDATA DD DSN=CFXPRESS.TEST.MIDWEST.SALES,DISP=(,CATLG), // UNIT=SYSDA,SPACE=(TRK,(20,5),RLSE), // DCB=(LRECL=500,BLKSIZE=10000,RECFM=FB) //INPUT DD * CONNECT APPLID(HIF0001) PCSCRIPT OPTION LANGLEVEL(3) CHDIR C:\MARKET FILES IF EXIST MIDWEST.SALES.DAT GOTO GOT_FILE ;DOES FILE EXIST? :NOFILE QUIT ; NOFILE, (QUIT SETS LASTRC = 4) :GOT_FILE END ; FILE EXISTS, (END SETS LASTRC = 0) /END UPLOAD RUNIF(LASTRC,EQ,0) DEV(DISK) PCFILE(MIDWEST.SALES.DAT) PCSCRIPT OPTION LANGLEVEL(3) IF NUM &LASTRC NE 0 GOTO NO_DELETE ; EVERYTHING OK? ON ERROR GOTO NO_DELETE DELETEFILE MIDWEST.SALES.DAT END :NO_DELETE QUIT ; NOFILE, (QUIT SETS LASTRC = 4) /END /* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //

Figure 3-9: Upload if PC file is available, then delete PC file

Example 3 - Downloads a file, copies it, adding the current date to its name, then notifies the PC user that the file was downloaded successfully.
//XPDNLOAD JOB (ACCT) /* --------------------------------------------------------------* /* PCMEXPRESS - DOWNLOAD A FILE, /* COPY WITH DATE AND NOTIFY USER /* --------------------------------------------------------------* //JOBLIB DD DSN=CFXPRESS.LOADLIB /* //XPDNLD1 EXEC PGM=CFXPRESS,PARM=LUNAME(SYS40028) //REPORT DD SYSOUT=* //CFXDATA DD DSN=CFXPRESS.TEST.STATFILE,DISP=SHR //INPUT DD * /*

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 31

CONNECT APPLID(HIFAPPL) DOWNLOAD DEV(ESDS) PCFILE(C:\PCM_EXP\STATS.DAT) * PCSCRIPT OPTION LANGLEVEL(3) IF NUM &LASTRC NE 0 GOTO NO_GO ; EVERYTHING OK? :SETUP ON ERROR GOTO NO_GO SET #FD1 = @SUBSTR(@DATE, 1, 2) ; GET MMDD FOR FILENAME SET #FD2 = @SUBSTR(@DATE, 4, 2) SET #mmdd = #fd1 #fd2 :COPY1 CHDIR C:\MARKET FILES ; GO TO MARKET DIRECTORY SET #FNAME = @STRCAT(MIDWEST.STATS., #MMDD, .DAT) COPYFILE C:\PCM_EXP\STATS.DAT TO @STRCAT(\PCM_WIN\STATS.DAT, #FNAME) :NOTIFY1 ;NOTIFY USER TIMEOUT(30) ON TIMEOUT GOTO NO_USER ;IF NO RESPONSE, JUST LEAVE DLGBOX NEW DLGBOX line1=Midwest Market File DLGBOX line2=@STRCAT(for: , #mmdd, Downloaded) DLGBOX button1=OK DLGBOX EXECUTE :NO_USER ;IF NO RESPONSE OR OK END :NO_GO ;IF UNABLE TO COPY QUIT(33) /END //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //

Figure 3-10: Download a file, with copyfile and notification procedures

Example 4 - Downloads a file, runs an external process to send/receive data from client sites, checks the status of this external process, then uploads any transaction file(s) that were received from clients.
//XPDNEXEC JOB (ACCT) /* --------------------------------------------------------------* /* PCMEXPRESS - DOWNLOAD A FILE, /* COPY WITH DATE AND NOTIFY USER /* --------------------------------------------------------------* //JOBLIB DD DSN=CFXPRESS.LOADLIB /* //XPDNEX1 EXEC PGM=CFXPRESS,PARM=LUNAME(CF32701) //REPORT DD SYSOUT=* //KDSDIN DD DSN=VSAM.KSDS.PRICE,DISP=SHR //EDSDOUT DD DSN=VSAM.ESDS.ORDER,DISP=SHR //INPUT DD * CONNECT APPLID(HIF0001) DOWNLOAD DEV(KSDS) PCFILE(C:\MARKET FILES\MIDWEST.PRICE.DAT) DDNAME(KSDSIN) * PCSCRIPT OPTION LANGLEVEL(3) IF NUM &LASTRC NE 0 GOTO NO_GO ; EVERYTHING OK? * ;RUN THE EXTERNAL SEND/RECEIVE PROCESS :SEND_RECV CHDIR C:\PCPLUS RUN C:\PCPLUS\PCPLUS /FC:\PCPLUS\DIALSITE.ASP * ;CHECK RETURN FROM PCPLUS * ;RECORD IS: NN1,NN2 (NN1=RC, NN2=COUNT) ON FILE_ERROR GOTO BAD_DIAL1 ON END_OF_FILE GOTO BAD_DIAL1 * OPEN (1) DIALSITE.RC READ READ (1) NUM #RC, #FCOUNT CLOSE (1) IF NUM #RC > 0 GOTO BAD_DIAL * :SET_FILES * SET #FD1 = @SUBSTR(@DATE, 1, 2) ; GET MMDD FOR FILENAME SET #FD2 = @SUBSTR(@DATE, 4, 2)

32 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

SET #MMDD = #FD1 #FD2 CALC #SEQ = 0 CALC #QUITRC = 33 + #FCOUNT ; SET RC FOR QUIT * :LOOP_COPY ; COPY FILES FOR UPLOAD CALC #SEQ = #SEQ + 1 IF NUM #SEQ > #FCOUNT THEN GOTO END_COPY ENDIF * ------------------------------------------------------------------* COPY FILES TO UPLOAD DIRECTORY, DELETE OLD! * ;OLD NAME, EG: ORDER1.DAT * ORDER2.DAT * ;NEW NAME, EG: SITE1.ORDER1.DAT * SITE1.ORDER2.DAT * ------------------------------------------------------------------SET OFILE = @STRCAT(C:\PCPLUS\ORDER, #SEQ, .DAT) SET NFILE = @STRCAT(C:\MARKET FILES\SITE1.ORDER, #SEQ, .DAT) COPYFILE #OFILE TO #NFILE DELETEFILE #OFILE GOTO LOOP_COPY * :END_COPY QUIT(#QUITRC) ;SET USERRC = 33 + NUMBER OF FILES TO Upload * ------------------------------------------------------------------:BAD_DIAL QUIT(255) ;SET JOB RC TO 15, NO FURTHER PROCESSING :BAD_DIAL1 QUIT(254) ;SET JOB RC TO 14, NO FURTHER PROCESSING :NO_GO QUIT(253) ;SET JOB RC TO 13, NO FURTHER PROCESSING /END * UPLOAD RUNIF(USERRC,GT,33) DEV(ESDS) DDNAME(ESDSOUT) PCFILE(C:\MARKET FILES\SITE1.ORDER1.DAT) UPLOAD RUNIF(USERRC,GT,34) DEV(ESDS) DDNAME(ESDSOUT) PCFILE(C:\MARKET FILES\SITE1.ORDER2.DAT) UPLOAD RUNIF(USERRC,GT,35) DEV(ESDS) DDNAME(ESDSOUT) PCFILE(C:\MARKET FILES\SITE1.ORDER3.DAT) UPLOAD RUNIF(USERRC,GT,36) DEV(ESDS) DDNAME(ESDSOUT) PCFILE(C:\MARKET FILES\SITE1.ORDER4.DAT) /* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //

Figure 3-11: Download a file, run external process, then upload transaction files

pcMAINFRAME Express

Chapter 3 - Mainframe Processing 33

34 Chapter 3 - Mainframe Processing

pcMAINFRAME Express

Chapter 4 - PC Installation

pcmExpress Installation
Requirements
This section explains how to install pcMAINFRAME Express on your PC. Before you begin, make sure that you have the following necessary items: The pcMAINFRAME Express CD-ROM. A PC (IBM or 100% compatible) with a hard disk drive containing at least 10 megabytes of available disk space. CD-ROM Drive or a network connection for installation from a network drive. Microsoft Win95, Win98, Win/NT (v4.0 or above) or Windows 2000. One or more of the supported communications facilities. This might be an IBM coax card connected to your host, TCP/IP or one of many 3270 emulator products that provide a HLLAPI interface.

The pcMAINFRAME Express installation process requires that you select a communications environment and define the installed program directory. If you wish to terminate the installation at any time, click on the ,3.0 button to stop the procedure.

Installation Process
To start the install process, place the pcMAINFRAME Express CD-ROM into your drive and run Install. If your CD-ROM drive is set to AutoPlay, the installation process will start automatically. Select Install pcMAINFRAME Express from the installation menu. The installation splash and a progress bar will display while setup is preparing to install.

pcMAINFRAME Express

Chapter 4 - PC Installation 35

Figure 4-1: Installation startup splash

Before the pcMAINFRAME Express programs and files are installed, you will be asked several questions regarding installation options. Follow the instructions that appear in each dialog box. After each selection, click on 0 9 to proceed through the installation. To change a selection, select the ,. button until you reach the desired option.

Figure 4-2: Installation type selection window

If you choose Network Server Installation at the above screen, the product should be installed on a network drive. The network installation will include all Express product files, as well as the setup files that will be used when Express is installed on individual workstations. This selection allows for later installation on individual workstations from the installed network directory. For these users, the application will be shared from the network installation. The next two screens are used to select the communication environment and your specific connection to the host.

36 Chapter 4 - PC Installation

pcMAINFRAME Express

Figure 4-3: Category of PC-to-Mainframe Communication

Select the general category of communications to be used. If you are unsure of the category, a brief explanation of each category is displayed if you press Help.

For direct TCP/IP support, select TCP Direct APPX Listener.

If your connection changes, use pcxsetup to change the device defined in the setup file to any supported driver.

Figure 4-4: Specific Communication Method

At the specific communication method screen, select the product or connection that you are currently using. This will be the default device used for the sample SETUP.XPR defined during installation. All communication drivers will be installed in addition to the selected driver. In the next panel, set the destination drive and directory for pcMAINFRAME Express. The default directory is C:\ PCM_EXP. You may change this selection by browsing to a different directory or typing a new directory name. A screen that allows you to name the folder for Express icons appears next. If you choose to override the default, the new name should be easily identifiable by the user.

pcMAINFRAME Express

Chapter 4 - PC Installation 37

Figure 4-5: Review of Express Installation Choices

The final screen is a review of the installation choices. If you choose to continue, all files and programs will be installed.

TCP/IP Listener Installation

pcmExpress will launch the TPNS install if you ' the APPX TPNS install query at the end of the pcmExpress installation The TCP/IP listener (APPX TPN Service) must be installed if a direct TCP/IP connection is to be used. To run the Listener install, return to the pcMAINFRAME Express CD-ROM Install menu, and select Install APPX TPN Service. Listener programs and configuration files will be installed in the directory specified. The default directory, \PCM_EXP\APPXTPNS\ should be used unless Express was installed in a non-standard directory. In this case, install into a sub-directory of the Express installation directory. The APPX TPN Service Configuration program and APPX TPN Service Manager will be added to the pcMAINFRAME Express program folder, and appropriate registry entries will be added.

Install Online Documentation

To obtain an online version of this manual and additional device and TPN service documentation, return to the pcMAINFRAME Express CD-ROM Install menu, and select Install Online Documentation from the installation menu. PDF versions of the following manuals will be installed: Guide to Express Dialog Programmers Guide APPX Service Implementation Guide and Reference

38 Chapter 4 - PC Installation

pcMAINFRAME Express

APPX Router Implementation Guide and Reference Note. Adobes Acrobat Reader is required to view PDF files.

Ready for Transfer

PC installation of pcMAINFRAME Express is now complete. All programs and files ed to configure and run pcMAINFRAME Express have been added to the xpress folder. See Chapter 5 - PC User Guide for detailed instruction on how to setup and run PCXPRESS on your PC.

pcMAINFRAME Express

Chapter 4 - PC Installation 39

40 Chapter 4 - PC Installation

pcMAINFRAME Express

Chapter 5 - PC User Guide

Introduction
This user guide is divided into three sections. The first, Using PCXPRESS, will explain how the mainframe communicates with your PC and detail the steps necessary to get the PC ready to accept the host initiated transfer request. The second, Using PCXSETUP, explains how to create and maintain the setup files needed to run PCXPRESS. Finally, the section Support Components will summarize the special configuration and trouble shooting facilities that are available. You should have already installed pcMAINFRAME Express on your PC. If you have not, complete installation instructions can be found in Chapter 4 - PC Installation.

Using PCXPRESS
PCXPRESS is meant to run with the PC with minimal effort. Once started, the application can be minimized and should need no additional attention. When a host file transfer is directed to your PC, the process will begin and end without any intervention. The mainframe job may be set up to notify you that a transfer has completed or is about to start, but this is optional and should be used only when necessary or helpful. Although Express runs without any user intervention, a certain amount of setup and configuration is required. The default files and settings established during installation may need to be updated. Finally, the application must be made ready for transfer. Requirements are dependent on the connection being used. The following describe the steps needed to ready PCXPRESS for each supported communications environment.

LU2 (3270) Connections

Before running, you should make sure that any required 3270 emulation software is loaded on your PC. A 3270 session must be started and the session must be available to VTAM for the host transfer process. This means that the display should be at a

pcMAINFRAME Express

Chapter 5 - PC User Guide 41

VTAM menu or login screen. The host application then attaches to this session and directs data to the PC that has started the session. On completion of the host job, the 3270 session should be returned to the VTAM menu display. To get ready for transfers, double click on the PCX icon in the pcmExpress folder. Note: when you start the program with this icon, a file named SETUP.XPR is used to obtain run-time information. It is created during installation and can be customized to automate the PROLOG process that is defined below. On startup, the Express splash screen will display copyright and release information.

PROLOG Processing
After the startup splash, the PROLOG script is executed. This process makes the initial connection to your emulator and should be used to get the terminal session to a VTAM menu. The sample setup file has a generalized PROLOG script coded that will allow you to go to terminal entry mode (manual mode) to make sure that your 3270 session is ready at a VTAM menu. This script puts up a dialog box that allows you to choose either Manual or OK. Select ,3:, to enter terminal mode. If your session is at a VTAM menu screen, select to go directly to the host wait state.

Figure 5-1: Prolog Manual Mode dialog screen

After you click on ,3:, , the Prolog Emulation window will be displayed (Figure 5-2: Terminal Entry Mode) and you will be placed in manual entry mode.

42 Chapter 5 - PC User Guide

pcMAINFRAME Express

While in manual entry mode, the (Clear) key is (F2) on the PC keyboard, and the Reset key is (F10) on the PC keyboard. A complete keyboard map is located in Appendix A Configuration for Commonly Used Devices. The manual login process described above can be automated by updating the PROLOG script in the setup file

Figure 5-2: Terminal Entry Mode

During manual mode, you may perform normal 3270 key entry to navigate to the VTAM menu. The default keyboard may be different from the one youre used to. See Appendix A for a complete keyboard map, or use the Keys menu selection to enter a specific 3270 key. When the VTAM menu screen is displayed, click on End! To exit manual mode.

Host Wait State

After Prolog processing, the Express screen will display the message Waiting for host initiation. You are now in the host wait state and your PC will is ready to process transfers directed to the terminal attached to your PC. If you minimize the Express window at this point, no further action is necessary. The application will continue to run until you select Exit from the menu bar or close the PCXPRESS window. Proceed to the Transfer Processing section of this chapter

Direct TCP/IP Connections

For direct TCP/IP connections, the pcmExpress application is started whenever a host sends a file transfer request to the PC. The APPX TPN Service manager must be running to wait for (listen for) incoming traffic and start the transfer program PCXPRESS. The TPN service manager must be configured and started before transfers can take place.

APPX TPNS Configuration

See the online APPX TPN Service Implementation Guide and Reference for additional configuration information. A default TPN Service configuration file was created when APPX TPNS was installed. This file should be reviewed and modified if necessary. The APPX TPNS configuration has two parts: Listeners and TPN Definitions. 1. The Listener section defines the TCP/IP ports that will accept a connection from the mainframe transfer program. 2. The TPN Definition defines PCXPRESS.EXE as the program that will be run for those clients.

pcMAINFRAME Express

Chapter 5 - PC User Guide 43

To review the file created for you at install, open the APPX TPNS Service Configuration icon in the Express program folder. Select File and OpenActive from the Menu Bar. The Active configuration is used when the TPN service Manager is started.

Figure 5-3: TPN Configuration - Global Settings

To update these settings, select Edit / Properties from the menu bar, or click on the properties icon on the tool bar. The Start TPN Service Automatically option should be checked. This will automatically start the TPN service manager when the workstation is started. Normally, other values here do not need to be changed. Next, select the TPN Definition PCXPRESS to display the default TPN values.

Figure 5-4: Default TPN values for PCXPRESS

The TPN is set to run program PCXPRESS on the PC, with the default setup file, INITTCP.XPR, that was created during installation. Change the directory only if Express was installed in a directory other than the default. To display listener connection information, highlight a listener Port address.

44 Chapter 5 - PC User Guide

pcMAINFRAME Express

Figure 5-5: TPNS Port configuration

Data for each listener defines the TCP/IP port address that will be used to wait for incoming connections. The assignment is arbitrary, but should be in a range from 1025-65534. The mainframe application CFXPRESS will use this port number, as well as the actual TCP/IP address, to direct transfer data to the PC. After configuration data is reviewed and updated as necessary, select File and Save As Active.

Start APPX TPN Services

The APPX TPN Service Manager is used to control TPN sessions. It is uses the Active configuration file to start the TPN service and individual listeners. Normally, the TPNS Service Manager will be started when the workstation is booted. To start the Service Manager manually, double click the APPX TPN Service Manager icon from the pcmExpress program folder. When the Service Manager is started, a panel with two tabs, Listeners and Sessions, will be shown From the Service Manager 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. If configured with the Start TPN Service Automatically option, the service manager will be brought up when the PC is started. For more information on using the service manager and viewing the event log, see the Support Components section later in this chapter.

LU6.2 Connections
For LU6.2 connections, the transfer application will be started when the host establishes an LU6.2 session on the PC. For detailed information on LU6.2 configuration requirements, see Appendix A - Configuration for Commonly Used Devices.

pcMAINFRAME Express

Chapter 5 - PC User Guide 45

Transfer Processing
Once a transfer is started, PCXPRESS will complete the requested operations automatically. The host can initiate PC processing as well as uploads and downloads.

Transfer Statistics Window

During transfers, progress is displayed in the transfer statistics window. The window can be minimized or restored to view ongoing status.

Figure 5-6: Transfer Statistics Window

The following transfer detail fields are displayed in the Transfer Statistics window: Uploading to mainframe as Fixed: The title bar shows the transfer direction and the PC file format. Profile: Indicates a full file transfer with no field selection or reformatting. PC File: Shows the name of the PC file being transferred. Records Transferred: Shows the number of records that have been sent or received. This count is updated every 10 records. Elapsed Time: Shows the time (HH:MM:SS) since transfer initiation. Source or Target Directory Shows the full name of the PC files source or target directory. To view the data being transferred, you may click on will be displayed. To close this window, click on the
,9, 3/4

. Every tenth record

Figure 5-7: Active Data Window

Note: processing overhead is incurred while the data window is open, slowing the transfer slightly. This window should be closed for best performance.

46 Chapter 5 - PC User Guide

pcMAINFRAME Express

Epilog Processing
On completion of a session, any EPILOG script that has been coded will run, then the application will end or, for 3270 connections, return to the host Wait State. Note: the 3270 session should be returned to the VTAM menu display, ready for the next host request. To end all processing, click on Exit. A new window, Exit will end Host Wait State or #08:20 will appear, and verification will be required by choosing either the buttons. This is the preferable way to end the Wait for Host State.

PC Logging
Express produces a LOG file every time PCXPRESS is run. The file is placed in the same directory as the setup file, unless a LOGDIR has been specified. The file is given the same name as the setup file, with a .LOG extension. The log contains startup information, all transfer activity, and any user or error messages. The log file is overlaid whenever PCXPRESS is started, so it contains only the most recent activity. If the HISTORY option is selected, an additional file, with a .HST extension, will be created. Each new session log will be appended to the end of the history log. This file will continue to grow and should be periodically reviewed and maintained.
[pcmEXPRESS v2.10 SESSION LOG]

[SESSIONSTART] DESC=Sample pcmExpress setup DATE=02/12/1999 TIME=11:09:07 [PROLOG] START=11:09:08 MESSAGE=Waiting for HOST Initiation. Wait Count: 01 END=11:11:30 [CONNECT] DEVICE=IBM UPLOAD COMPRESS=ADVANCED-A4 DOWNLOAD COMPRESS=ADVANCED-A4 MESSAGE=Obtaining transfer data from HOST (V2.00) [TRANSFER] BEGINTIME=11:11:35 FUNCTION=UPLOAD PROFILE=BULKUP PCFILE=H:\PCMFTEST\UPDATA\PCMXALL.1 ENDTIME=11:15:49 RECORDS=6,000 STATUS=OK DATABYTES=3,270,000 DATARATE=772,441cpm COMPRESSION=73.0% [EPILOG] START=11:15:49 END=11:15:49 [PROLOG] START=11:15:49 MESSAGE=Waiting for HOST Initiation. Wait Count: 02 END=11:16:02 MESSAGE=PC processing ended due to user EXIT request [SESSIONEND] DATE=02/12/1999 TIME=11:16:02 RETURNCODE=00

Figure 5-8: Session Log

The icon labeled Log Reader uses Notepad to open the log file named SETUP.LOG. You can open, review and maintain any .LOG or .HST with this application.

pcMAINFRAME Express

Chapter 5 - PC User Guide 47

Using PCXSETUP
A configuration file, called the setup file, is required to run PCXPRESS. A sample file, named SETUP.XPR is created during installation. The setup file is used to define communications and processing options to PCXPRESS. It is a formatted text file that contains all information needed to start, execute and end a transfer session. A setup file must be specified for a transfer to take place (that is, to run PCXPRESS). Each PC using pcMAINFRAME Express usually has its own, unique setup file. This file specifies the type of communication device to use and various runtime settings. A setup file can also contain a PROLOG or EPILOG script to navigate to a VTAM menu. Setup files are divided into four sections, as defined below: Options - Special processing options that are available. Optional. Parameters - Communications environment and run time processing options. Required. Prolog - A dialog script that can be executed before host initiation is started. This script automates any 3270 operations (clearing any pending operations, getting to a VTAM menu, etc.) or PC processes that are routinely performed prior to waiting for host initiation. Optional. Epilog - A dialog script that can be executed after host initiation processing is complete. This script automates any 3270 operations (clearing any pending operations, getting to a VTAM menu, etc.) or PC processes that are routinely performed after host initiated transfers are complete. Optional.

Language Support
The default language for Express is English. Other supported languages are French, Spanish, Italian and Portuguese. If you change the language setting for your PC to any supported language, Express will display screens and messages in the language of your choice.

To Begin
To start PCXSETUP, select the pcMAINFRAME Express application group and double click on the PCXSETUP icon, or select the icon and press enter.

Figure 5-9: pcmExpress Release Logo

After the release logo is displayed, the application workspace will clear and the setup file maintenance windows are activated. The name of the current OPEN file will be

48 Chapter 5 - PC User Guide

pcMAINFRAME Express

shown on the title bar. If no file is open and during NEW file processing, the title bar will show Untitled.

Menu Bar Functions

There are three primary functions provided on the menu bar. They are used as follows:

File provides the following file options:

New: create a new file. Open: Open an existing file. Save: Save an existing file. saveAs: Save an existing file with a new name Exit: Exit the PCXSETUP application. Note: If the current file has been changed but not saved, you will be asked if you want to save the current file before a new file request is handled.

Options provides settings for special processing options.

Edit Text is a toggle used to put PCXSETUP into a full-screen edit mode. When eText is ON, any ASCII text file (including setup files) can be viewed and changed directly. The setup section windows will be closed during eText processing. Write Encrypted allows you to encrypt your setup file and assign it a password. Note: The above settings can be set at any time during processing. They will not change until a file with a conflicting setting is opened. For example, if encryption is off but an encrypted file is read, the setting will be reset to encryption ON.

Window provide a list of the setup application windows. A selected

window will be moved on top.

Editing Setup Files

To create or change a setup file, click File on the menu bar and select New or Open. If you select Open, you must enter the desired file name in the file select window. If a file is specified on the command line, it will be opened on startup. Note that changes made to a file will not be lost while switching among windows BUT are not permanent until a File Save is requested. Once a file is open, you can begin to make changes. The cursor will be positioned in the first active field. This field will be highlighted and its description will be displayed in a message box at the bottom of the screen. Only active fields can be edited. To move the cursor from field to field, use the mouse or the tab key. Any default values normally taken by pcMAINFRAME Express will be shown where fields are not otherwise valued. You may not open multiple files during any given edit session. Changes to a file should be saved before another file can be opened.

SETUP Screens
Field definitions and usage for each screen in the setup stack are defined below.

pcMAINFRAME Express

Chapter 5 - PC User Guide 49

Parameters Screen

Figure 5-10: Setup Parameters

The required fields in the Parameters section vary depending upon the device type you are using. For LU6.2 and TCP Direct, you may need to update the Advanced Parms window, which is discussed below. The following are Parameter fields: Description This field is optional. Enter up to forty characters of upper and lower case text describing the setup file. This description will be used during PC logging to describe the transfer session. See Appendix A for informattion on device specific configuration requirements. Comm Device This field defines the communication link between the PC and mainframe. pcMAINFRAME Express supports a variety of communication devices. To open the device selection window, click on the arrow and an alphabetical list of supported devices will appear. (You may also tab to the field and press E to scroll through the list.) To select a device, highlight the appropriate device and click on the mouse button, or press 3907 . To close the window without changing the current selection, press 8. , or tab to the next field. Host Session This field is required for devices that use a HLLAPI interface to an emulator, such as IBM Personal Communications for Windows, Extra! Personal Client, etc. It defines the host session short name associated with the 3270 session that Express should use for transfers. Run Mode This field defines how pcMAINFRAME Express trouble shooting support routines are to be invoked. Production mode is the normal mode for running a transfer. In Test mode, all 3270 screens sent or received during startup and endup scripts will be displayed. During transfer, the record count window is updated as each record is sent or received. Error trace and debug modes create external line or transfer trace files and should be used only if serious transmission errors have occurred.

50 Chapter 5 - PC User Guide

pcMAINFRAME Express

PC Logging This field defines the level of PC logging. Logs record transfer statistics and any error messages that might have occurred. To make the selection list appear, click on the arrow control, or tab to the field and press the down arrow key. Session indicates that a session log, to be named setup.LOG should be created. It will have the same name as the setup file with a suffix of LOG. History indicates that a history log file named setup.HST should be created in addition to the session log. If you choose History, be sure to periodically rename or delete this file. It will keep recording each time this particular PCX setup file is executed. None indicates that no PC logging is to take place.

Log DIR This field defines the directory that PC log files should be written to if you want the log file(s) to be kept separate from setup files. To do this, specify a fully qualified directory name. If this field is left blank, the log will be written to the directory that contains the setup file. Timeout The default amount of time that the PC will wait for a mainframe response during a file transfer is 32 seconds. Values between 1 and 255 represent the number of seconds the PC will wait. The PC issues an error message and disconnects if it has not received a response within this time. If response time from the mainframe is very slow, increase timeout seconds to the maximum of 255. Note: an N in this field will disable the PC timeout feature. This value should normally be used only during a trouble-shooting session. Advanced Parms Used to select the advanced parameters screen that defines parameters not commonly used, including those for LU6.2 and TCP/IP connections.

Advanced Parms Screen

Figure 5-11: Advanced Parms

pcMAINFRAME Express

Chapter 5 - PC User Guide 51

You may not edit any other windows while the Advanced Parms Window is displayed.

To exit this screen select either and restore previous values.

to save changes or

,3.0

to disregard changes

Upload Compression and Download Compression are used to define the advanced compression technique to use. The technique is a 2-character field that defines the compression method (byte 1) and the compression library size to use (byte 2). Valid values for Byte 1 are: * - Use the mainframe defined technique A - Method A (Lempel Zev) Valid values for Byte 2 are: Additional Memory Required 0 - Use the default library size Upload Download 1 - Dictionary size = 4K entries 25,060 16,384 2 - Dictionary size = 8K entries 49,165 32,768 3 - Dictionary size = 16K entries 99,805 65,536 4 - Dictionary size = 32K entries 196,615 131,072 Note: A4 is the default and should be used to obtain optimum performance. Text Translate Table ID Indicates that a special ASCII to EBCDIC or EBCDIC to ASCII table has been created with MAINXLAT, and is to be used for this transfer session. The XLATE-ID is the one-byte character assigned to identify the table. Max Buffer size The maximum buffer size to be used during data transfer. The largest buffer size supported by the connection should be used. For LU2 (3270 type) connections, this field can be left at 0. For most TCP/IP and LU6.2 connections, this field should be set between 4096 and 32000. LU 6.2 / TCP The fields in this box are only relevant to LU 6.2 or TCP/IP Direct communications devices and are ignored if any other device has been chosen for the Device parameter on the Parameters window. All of these fields are optional. Configuration Name Enter the Key of the MAINCON LU 6.2 configuration record to use. If left blank, the default configuration record will be used. LU Name Enter the name of the LU on which the mainframe component of pcMAINFRAME Express is running. (The LU is also known as the VTAM APPLID). If left blank, the Destination LU Name configured in MAINCON will be used. Mode Name Enter VTAM MODETAB to use for the LU 6.2 connection. See your SNA network administrator. If left blank, the Mode Name configured in MAINCON will be used. Side Info Name For CPIC LU 6.2 interfaces, enter the name of the Side Info to use for the connection. The LU 6.2 package on the PC will have a utility to create the side info records; this name must match one of them. If left blank, the Side Info Name configured in MAINCON will be used.

52 Chapter 5 - PC User Guide

pcMAINFRAME Express

Script Screens

Figure 5-12: Prolog Script Screen

For a complete discussion of Dialog scripting capabilities, see Across the Boards Dialog Programmers Guide.

Prolog and Epilog screens define optional Dialog scripts that run before and after host initiated processing occurs. These may be used to make sure that the PC is not logged into any host applications and is ready for host initiation. The menu option, Edit allows you to perform the simple word processing functions cut, copy and paste using the Windows clipboard.

Using Edit Text Mode

Figure 5-13: Text Editing

When eText (edit text) is selected from the Options pull down menu, the file currently being edited (if any) will be displayed as a standard text file. You may open and edit any standard ASCII text file with the eText option. This option has been provided specifically for processing SETUP files and external Dialog files that are used in conjunction with pcMAINFRAME Express.

pcMAINFRAME Express

Chapter 5 - PC User Guide 53

Using the eText full-screen editor is the same as using the Prolog and Epilog editor. Standard Windows conventions for insert/type over mode, selecting, cutting and pasting apply. This editor contains an additional menu option, Edit. When variables are defined in a setup file, the eText option is forced and the formatted windows do not appear. The format and syntax of setup file fields are summarized below.

Setup file - Structure Overview

The Setup file is a standard, CR/LF delimited text file divided into a maximum of four logical sections. Each section begins with a [SECTION HEADER] and is followed by one or more sets of KEYWORD=VALUE lines. Sections do not have to be defined in any special order, but there can be only one of each section type.

General Rules
The following general rules apply when building a setup file: 1. Each section header must start on a new line. 2. Each KEYWORD=VALUE must start on a new line. 3. The maximum line length is 255 bytes. 4. Standard tabbing is honored. 5. Leading spaces are ignored. Spaces after KEYWORD= are not valid. 6. An * at the beginning of a line defines a comment line. The following details each section header and the valid KEYWORD=VALUES within each section:

[OPTION]
WAITHOST=M.

[PARM]
DESC= Up to 40 character Description. DEVICE= Communications Device Abbreviation. HOST= A - Z or a - z or 0 9. TIMEOUT= 0 - 999 (seconds) or N (no timeout). LANGUAGE= Language name or abbreviation or number. 1= English 3= French 5= Italian 6= Spanish 7= Portuguese Abbreviation is the first 2 characters of above Language. PCLOG= SESSION / HISTORY / NONE. LOGDIR= Full Path for .log or .hst files. MODE= TEST / PROD / TRACE / DEBUG. BUFFSIZE= 128 to 32000. XLATID= 1 character translate table identifier.

54 Chapter 5 - PC User Guide

pcMAINFRAME Express

RECKEY= For TCP/IP and LU6.2 sessions, KEY of the MAINCON configuration record to use for connection parameters. COMPRESS= U for upload, D for download, Y for both. UCOPTION= A1 / A2 / A3 / A4. DCOPTION= A1 / A2 / A3 /A4. LUNAME= for LU6.2 connections, the name of the host LU that the PC should connect to. This field is also known as the VTAM APPLID. MODENAME= the VTAM MODETAB to use for an LU 6.2 connection. SINAME= Side Information Name. For CPIC LU6.2 interfaces, the name of the Side Info record to use for the connection. HOSTNAME= for TCP/IP connections, the name or TCP/IP address of the host that the PC should connect to. TCPPORT= the Port Number on the host that a TCP/IP connection should use. For a complete guide to all the Dialog commands, see the Across the Boards, Dialog Programmers Guide.

[PROLOG]
Any valid dialog - to be run during prior to entering the host wait state.

[EPILOG]
Any valid dialog - to be run on completion of a host initiated session..

Setup File Variables

Definition of setup file values can be deferred until execution time with the use of variables. Variables are words that begin with an & (standard variable) or a $ (secured variable). They can be up to 32 characters in length and are delimited with a space. These variables will be resolved at run time in one of two ways: From the command line. Where /&vairable=VALUE is specified with the target program name on the application startup line. For example, if the setup file contains a variable named &LogDir, the command line MAINW SAMPLE.PCM /&LogDir=C:\PCM_EXP\logs would cause the log files to be written to the specified directory. By prompting the user when MAINW is started. Unresolved variables will be prompted for at the beginning of processing.

Rules for Coding Variables

Any value in the setup file can be defined as a variable. Typically setup files used to specify Host Initiated transfers do not need runtime variables. If desired, a variable can be coded in placed of any test parameter in the setup file. If set text is to be combined with a variable, then the text must be enclosed in quotes. Any spaces between the variable and the text will be removed from the resulting value. If any variable prefix occurs within a quoted string (data enclosed within a pair of apostrophes or quotation marks), then it is not treated as a variable. For example, to build a Directory name that consists of : A known root directory (C:\PCM_EXP\) and A sub directory for a specified user, in this case MARY.

pcMAINFRAME Express

Chapter 5 - PC User Guide 55

The variable would be coded: LOGDIR='C:\PCM_EXP\' %USERDIR The resolved directory name will be: C:\PCM_WIN\MARY

Support Components
pcMAINFRAME Express provides several applications that can be used to view logs or additional documentation, to perform special configuration if required, and to assist us with trouble shooting. These components are described below.

The CFXATB.INI File

Information regarding the location of application files and executables, as well as communications options, are stored in a file called CFXATB.INI in your systems WINDOWS directory. This file is created during installation and should be modified only when system parameters change. The following summarizes the sections of the file that are used by Express. ATB Section The ATB section contains global information used by all components of Express. [ATB] Path=path Device=dev Host=host path: The search path to be used to find all configuration files and drivers. Note: if the /P parameter is coded on the command line, it will take precedence. device: The ATB number or symbolic name of the communications device to be used for the session. Note: if the /M parameter is coded on the command line, it will take precedence. host: The ATB host session to be used. This may be A-Z or, less commonly, 0-9. Note: if a host session is coded in the setup file, it will take precedence. CFXDLG2 Section The CFXDLG2 section contains information used by the Dialog User Interface Module. [CFXDLG2] DIALOG_Color=color DIALOG_Font=font DIALOG_Cursor_Blink=blink_rate DIALOG_Cursor_Following=cursor_following DIALOG_WindowPosSave=pos_save DIALOG_Cursor_Mouse_Click=cursor_mouse DIALOG_EABs=eabs DIALOG_WindowMaxed=winmax DIALOG_SaveSettings=save_settings DIALOG_Alarm=alarm DIALOG_LastFont=last_font DIALOG_Reverse_Video=reverse_video

56 Chapter 5 - PC User Guide

pcMAINFRAME Express

color: The color set to use, valid values are Mono, Gray, Green, Color font: The font to use during Dialog terminal display. Valid values are Auto, 6x8, 7x8, 8x8, 8x12, 6x16, 7x16, 8x16, 10x20 blink_rate: The cursor Blink Rate. Valid values are Slow, Medium, Fast. cursor_following: Allow cursor following feature, valid value are Off, On. pos_save: Save and restore window positions across dialog sessions. Valid values are Off, On cursor_mouse: Reposition cursor with a single mouse click. Valid values are Off, On. eabs: Use EABs. Valid values are Off, On winmax: Remembers whether a dialog session was in a maximized state or not. Valid values are Off, On. save_settings: Saves preference dialog box values at exit, valid values are Off, On. alarm: Turns audible alarms on, otherwise the menu bar will flash if this is set to Off. last_font: The last fixed pitch font selected in the drop down combobox. Valid values are 6x8, 7x8, 8x8, 8x12, 6x16, 7x16, 8x16, 10x20. reverse_video: Reverses foreground, background colors. Valid values are Off, On. PCM4 Section The PCM4 section contains data used by PCXPRESS, the file transfer control program. [PCM4] COMPRESS=compress POLLINTERVAL=interval compress: Overrides the advanced compression default. Valid values are Y(es), D(ownload only), and U(pload only). interval: The interval, in milliseconds, that the transfer application will cede to Windows for other applications during each peek message loop. The default is 2 milliseconds. A lower value may improve transfer rates.

APPX TPN SERVICES

The APPX TPNS Manager application is used to control APPX TPN services. It allows you to: 1. 2. 3. 4. 5. Start and stop the TPN Service and individual Listeners. View the status of the TPN Service. Stop TPNS sessions. Launch the Event Viewer utility. Launch the configuration program.

To activate the service manager, double click on the taskbar icon ( ) that is displayed in the taskbar tray when the APPX TPN service is running. If the TPN

pcMAINFRAME Express

Chapter 5 - PC User Guide 57

service is not running, use the service manager icon in the pcmExpress folder. The Service Manager panel with two tabs, Listeners and Sessions, is shown.

Figure 5-14: Service Manager, Running Status

The top half of the Listeners panel is a list of configured listeners, while the bottom part shows detailed statistics for the selected listener. The sessions tab presents a list of running sessions in the upper section, and detailed information about the selected session in the bottom of the panel.

.
Figure 5-15: Service, Sessions panel

Stopping TPNS Sessions

In an emergency, or while testing, it may become necessary to stop a running TPNS session. This is accomplished via the Action menu.

58 Chapter 5 - PC User Guide

pcMAINFRAME Express

Keep in mind that stopping a session could have important consequences, such as lost or duplicated data. As a rule, active sessions should not be stopped until a transfer is finished.

Launching the Event Viewer

During the course of operation, TPNS will log successful program executions, along with any difficulties it may encounter in the event log. As a convenience, the event viewer may be launched from the Window option of the TPN Service Manager menu. Note, When running Windows NT/2000, the Windows NT Event Log viewer will be started; When running Windows 95/98, the APPX TPNS Event Viewer will be started.

Device Configuration
This icon is used to run our configuration application when necessary. In most cases, the defaults taken by pcmExpress and Dialog are correct and allow the use of a communications device without any further configuration. For devices requiring configuration (for example, LU 6.2 devices), or if the defaults are inappropriate for your configuration, the program MAINCON is used to create the appropriate configuration files. In addition, MAINCON can be used to configure display, keyboard and troubleshooting options. See Appendix A - Configuration for Commonly used Devices for more information about MAINCON.

Dialog
This 3270 scripting facility is included with pcMAINFRAME Express. It can be used as a terminal emulator or to run a script command file. Scripts can be used to automate such functions as navigating through VM and VTAM, keying repetitive data entry transactions, launching PC applications or performing PC file maintenance (copy, move, rename and delete). For detailed information on Dialog script commands and capabilities, refer to the Across the Boards Dialog Programmers Guide.

Log Reader
This facility, which makes use of Microsofts Notepad, can be used to quickly access PCXPRESS log files. By accessing The Log Reader, the file SETUP.LOG will automatically open. This file will show the most recent activity of the XPR file. You can access any of the .LOG or .HST files by this method.

Trace Download
This application is used to download a mainframe trace file that has been created during trouble shooting. This facility is rarely needed, and should only be used after consultation with cfSOFTWARE technical support.

pcMAINFRAME Express

Chapter 5 - PC User Guide 59

60 Chapter 5 - PC User Guide

pcMAINFRAME Express

Chapter 6 - Messages

Troubleshooting
Problems can occur at several different points during pcMAINFRAME Express processing: Before communications have been established While trying to establish communications When the host attempts to connect to your terminal session During a host initiated script or transfer Each potential trouble point usually indicates a different type of problem and different possible solutions. Since Express is often run in the background, it is usually necessary to review the log file to determine the type of error that has occurred. The log file can be found in the same directory as the setup file (*.xpr) that was used when running PCXPRESS. The PC log file records the text of any error message that are encountered during processing and often can pinpoint the exact cause of the problem. Sometimes, the error message contains status and return codes that have been received from an intermediate process, such as VTAM, APPX or a third party emulator. It is usually necessary to contact cfSOFTWARE Technical Support to help you resolve these types of problems.

Pre-Communications Errors
Pre-communications errors occur during the initial program startup and before the PROLOG script is invoked. Usually the errors that occur here are caused by one of two things: A missing or invalid setup file. Make sure that the setup file specified is present in the directory and that all data is valid. The log file will indicate the specific type of setup file error. A bad installation or invalid data in the CFXATB.INI file This problem usually results in a message indicating that a critical windows or server error has occurred. Make sure the PATH= statement in the CFXATB.INI file points to the current Express installation directory.

pcMAINFRAME Express

Chapter 6 - Messages 61

Communications Startup Errors

Communications startup occurs once the PROLOG script is invoked. The message Waiting for Host Initiation is displayed at this time. This is when Express loads the appropriate device driver and attempts to establish a connection to the 3270 session. The problems that can occur in this phase generally have to do with the configuration of software on the PC. These may be related to pcMAINFRAME Express and the files that it requires, or to the emulation software that is running. If a HLLAPI is needed, it must be loaded and attached with the correct host session short name. During communications startup, pcMAINFRAME Express loads a device driver file, CFX____.DLL. If these files cannot be located by pcMAINFRAME Express, or if the wrong configuration files are located and used, errors can occur

Errors at Host Connect

Errors may also occur when the host job directs a transfer to your PC. Usually, the PC user will not be aware of any problem, as the error information is recorded with the mainframe job. An error at this point usually indicates that the 3270 session is not available to VTAM, or that the LUID specified in the job does not match the actual session ID.

Errors while running Transfers or PC Scripts

Once communications between the PC and mainframe has been established, the message obtaining transfer data from Host is displayed. This signals the beginning of the Host Controlled phase of communication. At this point, the mainframe directs the processing on the PC. Files can be uploaded or downloaded, and PC scripts may be downloaded and executed. If a critical error does occur, as much information as possible about the problem will be recorded in the PC log. Often, problems of this nature will require additional analysis by your systems support and/or cfSOFTWARE technical support.

Contacting cfSOFTWARE for Problem Resolution

The cfSOFTWARE technical support number is (847) 824-7180. If you have difficulties that the above suggestions do not resolve, gather as much information as possible before calling for support, including: The PC log file The mainframe Control and Transfer reports Product information (name and version) of your emulation software The mainframe JCL and Command file

62 Chapter 6 - Messages

pcMAINFRAME Express

Messages
This section lists messages that may be displayed on the PC screen during an Express session. Most of them are purely informational while others may indicate errors that have occurred. Informational messages will appear on the PC screen, while error and statistical messages will be written to the hard copy log file. There are five different message formats: Messages with no numbers are generally informative messages that require no user response and are not an error. These messages are listed in alphabetical order in Information Messages. No logging of these messages takes place. Messages that are prefixed with PCH are issued by the mainframe and generally indicate an error that requires some user response. These messages are listed in numerical order in Mainframe Messages. All of these messages are logged at the mainframe and at the PC whenever possible. Messages prefixed with a two or three digit number are issued by the PC and generally indicate an error. These may require user response. These messages are listed in numerical order in PC Messages. Communications Messages lists messages numerically that result from logical or physical errors in pcMAINFRAME Express communications program. These may be logged in either the PC log or the mainframe log, or both. Setup Messages lists messages alphabetically that may be encountered while running the PCXSETUP program to create or modify setup files on the PC.

This manual is written for the persons who will administer the system at the mainframe and on the PCs. It is assumed that the reader will have a basic understanding of PC and mainframe processing.

Information Messages
Information messages appear routinely during Express operation in order to make processing easy for the PC user. The following is an alphabetical listing of the information messages you may view from your PC during a session. Note: these messages will not be output to the pcMAINFRAME Express logs.
Connecting to HOST for transfer data...

Explanation: The mainframe program is being started. The initial handshake with identification/version information exchange is completed. Action: None.

pcMAINFRAME Express

Chapter 6 - Messages 63

Downloading from mainframe as data type

Explanation: A download of data to the PC is in progress. Additional information about the download, including record counts and elapsed time, will also be displayed. Action: None. To interrupt the transfer in progress, press
,3.0

Error trace is on

Explanation: An option in the setup file or in MAINCON requesting a trace has been activated. Action: None.

Exit will end Host Wait State

#08:20

Explanation:  9 has been selected from the Waiting for HOST Initiation window. Action: To end pcMAINFRAME Express processing, select return to the Waiting for HOST Initiation state, select #08:20 . . To

Mainframe trace is on

Explanation: An option in the setup file or in Device Configuration requesting a trace has been activated. This should only be active during problem resolution. Action: None.

PC trace is on

Explanation: An option in the setup file or in Device Configuration requesting a trace has been activated. This should only be active when trying to resolve a problem. Action: None.

pcmEXPRESS canceled by PC operator

,3.0 *4 #08:20* #08:20*!74.088 !74.088

Explanation: The

,3.0

button was pressed during a file transfer.

Action: To cancel pcMAINFRAME Express immediately, select ,3.0 *4 . To resume the pcMAINFRAME Express session, select
#08:20*!74.088

64 Chapter 6 - Messages

pcMAINFRAME Express

Shutdown requested.
#08:20

Explanation: The (close) button on the PC active session was activated while a file transfer was processing. Action: To cancel Express immediately, select To resume the Express session, select
#08:20

Source Directory: directory_name

Explanation: This message appears at the bottom of the active window during an upload transfer. This displays the extended directory name of the sending file. Action: None.

Target Directory: directory_name

Explanation: This message appears at the bottom of the active window during a download transfer. This displays the extended directory name of the receiving file. Action: None.

Uploading to mainframe as data type

Explanation: An upload of data to the mainframe is in progress. Additional information about the upload, including record counts and elapsed time, will also be displayed. Action: None. To interrupt the transfer in progress, press
,3.0

Waiting for HOST Initiation

Explanation: After any processing of a Prolog script, or after the execution of a mainframe transfer job, this is the point where the PC is now waiting for the next mainframe job to be run, and the connection process to be started. Action: None.

Mainframe Messages
This section is a numerical listing of mainframe messages. These messages will be written to the PC log file (when possible), and be reported on the mainframe Control or Transfer report. When communications errors occur, messages may not reach the PC and they will not be recorded in the PC log. Mainframe messages generally indicate that an error has occurred. Following the text of each message is a description of the cause of the message and of the action that may be required. Messages that are prefixed with PCH are issued by the mainframe host initiation facility.

pcMAINFRAME Express

Chapter 6 - Messages 65

PC_002 Program name Error. Administrator.

Terminating.

Contact your System

Explanation: An error occurred in program name. Action: This pcMAINFRAME Express session terminates. Correct the error situation and resume.

PC_007 Program name Error: Administrator

Error code.

Contact your System

PC_027

Explanation: Program name has encountered the error code. This session is terminated. Action: Record this message. Contact cfSOFTWARE.
Length Error on File Name - Contact central site.

Explanation: pcMAINFRAME Express, in attempting to read from File name, encountered a wrong length record. Something has corrupted a pcMAINFRAME Express system file. Action: Restore the file in error from a backup.

PC_028

Unexpected disconnect received from PC.

PC_030

Explanation: The PC has issued a preemptive disconnect request during processing. Should not occur. Action: Retry transfer.

Unable to load Module:

Module name Error code

Explanation: An error has occurred in typing to load a module. Action: Review the error code and correct the problem. Re-run after correction.
APPX ERROR - RC - error message

PC_033

Explanation: A critical error has occurred during transfer processing. Action: Record the return code (RC) and error message. If this happened while a transfer was in progress, check to see if the mainframe job had terminated or if the PC operator had canceled the Express session. If this is still unresolved, contact cfSOFTWARE.
Initiating APPX session

PC_089

Explanation: The start of transfer exchange is taking place. Action: None.

66 Chapter 6 - Messages

pcMAINFRAME Express

PC_090

Establishing PC connection at hh:mm:ss

PC_092

Explanation: The initial connect between the mainframe and PC was attempted at this time. Action: None.

Transfer successfully completed at hh:mm:ss

PC_094

Explanation: This is an informational message showing the time the transfer successfully completed. Action: None.

Error during VTAM interface. Return Code : RC

Explanation: This warning message indicates that an error has happened during the VTAM interface. The return code displayed is further explained in the following message. Action: Look at the following message for more clarification.

PC_095

VTAM message : Msg Number : VTAM message

Explanation: This error message is issued when a transfer has canceled during the VTAM interface. Action: Some of the common errors and their possible reasons follow. If you cannot resolve the problem, be sure to contact cfSOFTWARE for problem resolution. 1005: Invalid state for request (error_code). This error may occur if the PC indicated by the LUNAME is not in a ready state. Be sure that you start the PC session before running the host job. (See the Example section for further explanation.) This may also occur if the execution of Express on the PC has been terminated, or the transfer session has been interrupted. Check the PC Log for further information. 1007: Timeout waiting for terminal response. This error may occur after initial connection has been made and either the mainframe or the PC jobs running were interrupted. 1011: ACB open failed: undefined/invalid applid name (error_code). Check to be sure that the APPLID indicated in the JCL has been defined correctly in the VTAM tables and is spelled correctly in the JCL. 1015: Invalid Target SLU ON (device) RC=(return code) SN=(sense switch). This may be caused if: 1) the PC indicated by the LUNAME is not in a ready state. Be sure that you start the PC session before running the host job. (See the Example section for further explanation) or 2) if your LUNAME in the host JCL is not matching the actual connection. 1016: Target SLU Busy (at Session Limit). This can be caused when either the PC setup file has been started and is unable to connect to VTAM due to the unavailability of a connection to the mainframe, or, during the Host Initiation process, when the mainframe job is trying to connect to the LUNAME. Check to see if the PC is at the appropriate

pcMAINFRAME Express

Chapter 6 - Messages 67

session, or, for a host initiation process, correctly connected to a VTAM menu screen.

PC_212

Upload record exceeds 32K bytes.

Explanation: The record size for an upload exceeds the maximum record size of 32,760 bytes. Action: Adjust the record size to meet specifications.

PC Messages
This section lists numerically PC messages that may be displayed on the PC during a pcMAINFRAME Express session. These messages are logged during automated processing. They generally indicate that an error has occurred. Following the text of each message is a description of the cause of the message and a description of the action that may be required.
20 Too many variables defined in file

Explanation: Up to 25 different variables can be defined in a Setup File or the Primary PC file of a Fixed Include type upload. This limit has been exceeded. Action: Reduce the number of variables in the indicated file.

30

Invalid Parameter on command line:

parm

Explanation: A command line parameter that pcMAINFRAME Express does not recognize has been passed on the command line. Action: Remove the invalid parameter and resubmit command to pcMAINFRAME Express.

31 Invalid Data in Setup File:

(nnnn) bad_data

Explanation: An unidentified or invalid parameter was encountered at line nnnn in the setup file. Action: Correct the invalid data and rerun.

32 Setup file name is invalid or missing

Explanation: The PC file specified on the command line can not be found (bad path or File name), or no setup file was specified on the command line. Action: Re-key the command with a valid setup file or startup procedure name. Make sure that the default drive is the correct one and that any valid drive specifications have been entered.

68 Chapter 6 - Messages

pcMAINFRAME Express

35 Session Canceled due to QUIT

Explanation: This message appears when PCXPRESS is canceled during startup verification or before a deferred startup time is reached. Action: None

101 Connect failed

Explanation: The initial handshake between the PC and Mainframe programs has failed. A further description of the reason for the failure is displayed on the second line of the message. Action: Should not occur. Contact cfSOFTWARE

102 APPX session error - Code:

RC

Explanation: A critical error occurred during a transfer session. RC indicates the APPX error code. An APPX error message further detailing the reason for the error appears on line 2 of the message. Action: Look-up the APPX error in the Communications Error messages section of this manual to determine the proper action. If no matching message is found, contact cfSOFTWARE.

103 Unexpected cancel or turn-around from mainframe

Explanation: The PC received a cancel or turn-around request from the Mainframe when it was not expected. This error indicates a serious breach of pcMAINFRAME Express communications protocol and should not occur. Action: Notify cfSOFTWARE.

104

Timed out waiting for response from mainframe

Explanation: The PC has sent a message, either data or control, to the host and has not received a response within the period specified by the Timeout parameter in the setup file. This message is displayed and the transmission is terminated. Action: Check host response time to determine why the timeout occurred. If there is a general problem with response time, increase the timeout value at the PC.

105 Unexpected disconnect received from mainframe

Explanation: The PC received a preemptive disconnect request from the Mainframe when it was not expected. This error indicates a serious breach of pcMAINFRAME Express communications protocol and should not occur. Action: Notify cfSOFTWARE.

pcMAINFRAME Express

Chapter 6 - Messages 69

106 Unexpected response from mainframe at Logon (R01) Receive . . . During Transfer . . . following Request to Send

Explanation: The PC, in the process of validating a response from the host, received an invalid response. The response did not conform to the pcMAINFRAME Express protocol. Action: Retry the transmission. If the error recurs, the second line of the error message contains the first 76 bytes of the bad response. The bad response usually indicates the source of the problem.

127 PC File not found

Explanation: The PC file defined for the transfer could not be found. Action: Check the disk drive and path specification to make sure the correct information was entered. Re-enter the drive, path and file name and retry the transfer.

140 Error during invoked DIALOG - Code:

RC

Explanation: A critical error occurred during a PCSCRIPT. RC indicates the dialog return code. A message detailing the reason for the error and the dialog statement in error are displayed. Action: Depending on the type of error:
RC=01 - syntax error. Correct the syntax error and rerun the job. RC=02 - communications error. Look up the error message in the

communications error section of this manual to determine the proper action.

RC=03 - timeout (a response was not received within the timeout limit

with no ON TIMEOUT). Correct any invalid wait for response, or add an ON TIMEOUT command to the dialog.
197 Connect warning: Safe Character Mode has been initiated.

Explanation: Safe character mode is used to overcome problems with special character mis-translations by a device (usually a protocol converter or controller). The mode is initiated by: setting safe-character mode ON with Device Configuration; or automatically, when the pcMAINFRAME Express connect protocol detects a character mistranslation.

Although safe character mode provides for fail-safe transmission of US-English language specific characters, some increased transfer overhead is required. Action: There is usually no need to run in this mode unless advised by Technical support at cfSOFTWARE. If pcMAINFRAME Express is dropping your transfers to safe-character mode, make sure that the Device Configuration safe-character mode flag (use the Troubleshooting option) is off. If this doesnt clear the message, contact cfSOFTWARE.

70 Chapter 6 - Messages

pcMAINFRAME Express

204

Error loading program:

nnnnnn RC

Explanation: Program nnnnnn could not be loaded. RC defines the reason: 02 = Program not found. 05 = Call to active program (program in use). 08 = Insufficient memory to load program. 11 = Program has invalid format.

Action: If RC = 02, make sure that the named program (nnnnn.EXE) is in the current directory or in a directory in the current PATH.

241

PC Script Error: Code RC.

242

Explanation: A statement coded in the PCSCRIPT section of the mainframe job is incorrect. Action: Check the statement for syntax and spelling.

PC Script Ended with Quit RC.

Explanation: A procedure coded in the PCSCRIPT section has returned with a programmer-coded return code. Action: Check the defined quit parameter to determine the cause for the return code.

243

PC Script Ended normally.

Explanation: A procedure coded in the PCSCRIPT section has executed without problem. Action: None.

Communications Messages
pcMAINFRAME Express uses a special program for its low level communications processing that can be broken down into three levels: CFXAPPX, CFXAPI and Dialog. When logical or physical errors occur in this program, it hands return codes and error messages to pcMAINFRAME Express. Where possible, pcMAINFRAME Express interprets the return codes and supplies its own error messages. At other times, the original message number and error code is passed on to the PC user. The following is a list of common result codes and messages that are returned from the program mentioned above:

pcMAINFRAME Express

Chapter 6 - Messages 71

Device Driver Messages

003: No LU/host-session connect.

Explanation: The Device Driver indicates that the host session letter/number defined in the setup file, configured by Device Configuration is invalid. Action: Check which host session SHORT-NAME (letter or number) is valid for your communications setup and either place that short-name in the setup file host session ID or use Device Configuration to configure it.

010:

Emulation card/software not found

Explanation: The Device Driver was unable to detect the specified emulation card and/or software on the PC. Action: Check to see that the emulation device code defined in the setup file is what you intended. See Appendix A - Configuration for Commonly Used Devices for information specific to your device. The I/O Ports, RAM address, API interrupt number, etc. for your device may have to be re-configured from their default values.

066: (Device Driver) - API DLL Load Failed

Explanation: The Device Drivers HLLAPI.DLL noted cannot be detected. Action: Terminate the pcMAINFRAME Express session. Check the communications link for an active mainframe connection. Insure that the device driver is configured for HLLAPI. Insure that the device type specified in your setup file is for the emulator product that your are running, and that the directory your emulator is installed in is in the search path. See the Device Configuration Chapter for information specific to your device. If the problem persists, contact cfSOFTWARE.

Device Driver specific message -

Explanation: The Device Driver has issued a message specific to the device type for a critical error. Action: If the problem persists, contact cfSOFTWARE.

72 Chapter 6 - Messages

pcMAINFRAME Express

XAPI Messages
120: DVC DRIVER xxxxxxx NOT FOUND (xx)

Explanation: The Device Driver named could not be found for load by XAPI. Action: If (xx) = 02, check to see that the Device Driver is accessible to the running application. If the Driver file is in a PC directory not accessible to the application, move the file to an accessible directory. If (xx) = 04 or 06, there are not enough file handles. Set the CONFIG.SYS FILES= parameter to a higher number and retry the application. If (xx) = 05, network access to the Driver file was denied. Contact your network administrator.

Any other message in the range of 001 to 199 indicates a logic error internal to XAPI and should be reported to cfSOFTWARE.

APPX Messages
220: Connection lost. Data sent was rejected. Code: XXX.

Explanation: If communication is via dial-up protocol converter, the line may have too much static. Action: Retry the session later. If the problem persists when other software is able to use the line without errors, contact cfSOFTWARE.
Data rcvd was rejected. Code: XXX.

230:

Connection lost.

Explanation: See error 220.

Any other message in the range 200 to 299 or 400 to 499 indicates a logic error internal to APPX and should be reported to cfSOFTWARE.

pcMAINFRAME Express

Chapter 6 - Messages 73

74 Chapter 6 - Messages

pcMAINFRAME Express

Appendix A - Configuration for Commonly used Devices

Configuration Overview
Using MAINCON
Communications device configuration, as well as video/keyboard customization, is done via the application called MAINCON.
MAINCON can be run by clicking on the Device Configuration icon. It displays its main menu (Figure 6-1 and pcMAINFRAME Device Configuration E. TCP/IP, DECNET 1. TELNET TN3270 2. TELNET VT20 3. DECNET VT220 4. TELNET VT320 5. APPZ/TCP 6. APPX/TCP - cfPPP 7. TN3270 w/TN3287 8. TELNET TN5250 5250 Emulation 1. PC Support AS/400 2. 5250 Emulation 3. 5250 HLLAPI G. LU6.2 Drivers 1. Dynacomm Elite 2. WinCPIC 3. IBM Personal Comm NT/95 4. Extra! NT/95 5. Rumba NT/95 6. WinAPPC NT/95 (SNA Server) 7. IBM Pers. Comm. NT/95 APPC

F.

X. Miscellaneous Drivers 1. cfMEMPIPE Driver

PgUp for more... Enter selection (eg. A1, D6, etc.) or press ESC to exit

Figure 6-2). Enter the two-character code associated with the menu entry and the selected configuration panel will be displayed. Alter the parameters as needed, and press  to save the configuration file. Note that some configurations have multiple screens which can be displayed by using ! &5 and ! 3 .

pcMAINFRAME Express

Appendix A - Configuration for Commonly used Devices 75

 pcMAINFRAME Device Configuration A. General Configuration 1. Video Mode/Keyboard 2. Trouble Shooting B. CUT-Mode/Single Session 3270 1. IBM 3270 Connection 2. DCA Irma 3. Forte 4. IDEA 5. AST Remote 6. Pathway Remote 7. Xircom Pocket 3270 D. Async/Protocol Converter 1. Comm Port Assignments 2. IBM 3101 3. DEC VT100 4. TYMNET78 5. TTY AND PC-to-PC 6. DEC VT220 7. DEC VT320

C. Gateways/HLLAPI, PS-API 1. HLLAPI/PS-API Host Session PgDn for more... 2. cfDFT (TCP/IP, LU6.2, DECNET 3. PCOX/CXI/Novell and 5250 on next page) 4. Banyan VINES Enter selection (eg. A1, D6, etc.) or press ESC to exit

Figure 6-1: MAINCON Menu page1

pcMAINFRAME Device Configuration E. TCP/IP, DECNET 1. TELNET TN3270 2. TELNET VT20 3. DECNET VT220 4. TELNET VT320 5. APPZ/TCP 6. APPX/TCP - cfPPP 7. TN3270 w/TN3287 8. TELNET TN5250 5250 Emulation 1. PC Support AS/400 2. 5250 Emulation 3. 5250 HLLAPI G. LU6.2 Drivers 1. Dynacomm Elite 2. WinCPIC 3. IBM Personal Comm NT/95 4. Extra! NT/95 5. Rumba NT/95 6. WinAPPC NT/95 (SNA Server) 7. IBM Pers. Comm. NT/95 APPC

F.

X. Miscellaneous Drivers 1. cfMEMPIPE Driver

PgUp for more... Enter selection (eg. A1, D6, etc.) or press ESC to exit

Figure 6-2: MAINCON Menu page 2

MAINCON Quick Notes

The MAINCON menu is divided into general categories of communication devices. The following notes summarize the configuration requirements for most common emulators used with pcMAINFRAME Express. The configuration panels referenced below are more fully documented in the following sections. 1. Most emulators supporting a HLLAPI (Windows 16-bit and 32-bit emulators) do not require any configuration other than the specification of the correct host session and device in the PCXPRESS setup file. Occasionally, some additional settings are required in the emulator product being used. 2. TCP/IP TELNET TN3270 drivers (E1) do not require configuration, but almost all installations will want to set the 3270 Terminal Model to 2E so that structured fields can be used for enhanced performance. 3. LU6.2 devices always require configuration. 4. For IBM 3278/79, IBM 3270 connection cards and compatibles (B1), as well as IRMA cards and compatibles (B2), the defaults are usually correct. Occasionally the RAM address or I/O port addresses must be configured. 5. The Video Mode/Keyboard configuration panel (A1) may be used to re-map the 3270 keyboard.

76 Appendix A - Configuration for Commonly used Devices

pcMAINFRAME Express

6.

Users with 3270 emulators or 3174s configured for languages other than U.S. English will need to set the Controller Language on the Video Mode/Keyboard configuration panel (A1).

Configuration for HLLAPI Emulators

32-bit Emulators
MAINCON Configuration - Usually, MAINCON configuration is not required. Emulator Configuration Many of the 32-bit emulator products require additional configuration before pcMAINFRAME Express can attach to the HLLAPI. These products include Attachmate Extra!, Dynacomm NS Elite Plus, Walldata Rumba, and IBM Personal Communications. Following are two of the most errors that occur when configuration is incomplete or incorrect. 140 Error during invoked dialog code (xx). This indicates a communication failure. This message will be followed by a further explanation of the exact error. 066: ____.dll load failure. Windows is not able to load the HLLAPI DLL specified in the message. Generally, this is caused when the emulator software being used is not containded in the system PATH. This can be resolved by modifying the PATH setting: WIN 95 - In the AUTOEXEC.BAT file, modify the path statement to include the full directory name of your installed emulation software, and reboot your system. WIN NT Modify the Path variable from the Control Panel / System / Environment tab to include the full directory of the installed emulation software. Note: you may need to be signed on as administrator to change this setting.

003: No LU/Host session connect. PCXPRESS cannot find or start an emulation session with the Host-Session ID specified in the setup file. The default setup file provided uses Host Session A, and it must match the host session ID (or session short name) assigned to the emualtors 3270 session Check the session short name defined for 3270 session being run. Each emulator package has a unique way of assigning the session short name, ususally from a connection or setting option on the session menu bar. If you are unable to find this option or change this setting, call cfSOFTWARE Technical Support for assistance. To connect to a session other than A, the setup file *.XPR should be changed.

16-bit Emulators
Most 16-bit emulator products run under Win95/98. pcMAINFRAME Express continues to support these emulators. MAINCON Configuration - Usually, MAINCON configuration is not required. Emulator Configuration Some emulators require special setup or configuration to enable their HLLAPI option. This often involves enabling a configuration option, or loading additional software. For example, ATTACHMATE EXTRA software: The EXTRA software must be resident and it must be configured for HLLAPI.

pcMAINFRAME Express

Appendix A - Configuration for Commonly used Devices 77

IBM Personal Communications 3270 software: The IBM software must be configured for HLLAPI with IBMs Setup program. Run Setup to the Advanced Configuration Options, Facilities screen and enable the HLLAPI entry. Occasionally, the emulators HLLAPI cannot be found, resulting in the error: 066: ____.dll load failure. Generally, this is caused when the emulator software being used is not containded in the system PATH. This can be resolved by modifying the PATH setting in your AUTOEXEC.BAT file to include the full directory name of your installed emulation software. A system reboot is required after this change.

3278/79 Coax Connections

Generally, there are no additional configuration requirements for Coax attached cards running in cut mode. Occasionally, the message Emulation card/software is not found is encountered. This can be caused by the failure to download micro-code onto the card before starting PCXPRESS, or if the I/O Port, RAM address, or API interrupt number has been customized for your PC. MAINCON Configuration - The MAINCON configuration panels for any of the common COAX cards allow you to specify the actual settings specified for your card. If you are unsure of any of your settings, or if you are unable to make a connection, be sure to call cfSOFTWARE Technical Support.

Configuration for TCP/IP - TN3270

pcMAINFRAME Device Configuration -------- Single Session TN3270 3270 Terminal Model..................... Trace size in K bytes................... Destination Port Number................. Disconnect Option tes................... Minimum Response Time ................. Accept Spurious Writes.................. Suppress TN3270E Mode................... Suppress DOIDs.......................... Non-TN3270E SysReq/Attn Mode............ 2E 0000 00023 0 0000 0 0 0 0

3270 model: 2 (24x80), 3 (32x80), 4 (43x80), or 5 (27x132). If EAB (extended attribute support) is desired, follow the model number with E. F10: write config to disk Esc: Exit

Figure 6-3: TCP/IP TN3270 Configuration Panel

The TCP/IP stack must be installed in Windows as appropriate. TCP/IP Windows Sockets is provided with Win95/98 and NT/2000, and is the most commonly used TCP/IP stack.

78 Appendix A - Configuration for Commonly used Devices

pcMAINFRAME Express

Since enhanced 3270 support must be configured for structured field support, Express is installed with a default configuration file, MAINCFG.TN3, that configures for model 2E.

AINCON Configuration: If MAINCON is not used to configure the TELNET TN3270 drivers, the driver will run as a basic (non-enhanced, non-SF) 3270 model 2 with no TCP/IP trace and will use the TELNET Well-Known-Port as the default (#23). If the host is capable of it, the enhanced 3270 support, which includes EABs and Structured Field support, should be configured by configuring the 3270 model as 2E, 3E, 4E or 5E. If the driver is configured for enhanced 3270 support, both the SF and non-SF connections are available. Only the non-SF APPX session is available with basic 3270 support. Note: most TN3270 hosts support the enhanced 3270 terminals. MAINCON can be used to enable a trace of the TCP/IP activity between the driver and the host. Entering a trace size other than zero will enable the trace. The trace data is kept in a circular buffer and will be written when the driver is closed. A file called TCPTRAC.BUF will be produced in the current working directory. The program TCPTRAC.EXE will format the TCPTRAC.BUF file. MAINCON can also be used to alter the default destination port on the host. If nothing is entered, MAINCON will default to the TELNET Well-Known-Port (#23). Operation of TELNET TN3270 Drivers These drivers implement all TN3270 functions including NVT mode if the host does not support TN3270. A new MAINCON configuration panel exists to support these drivers. This allows the configuration of terminal type (3270 models 2, 3, 4 or 5, with or without EABs and structured field support), the size of the internal trace buffer, and the default destination port address to use if the TELNET well-known-port is not being used. When first opened, the drivers display an NVT screen with a message requesting entry of the host name or address. The NVT screen consists of one enterable line (at the bottom), and a scrolling message area above the enterable area. 3270 field attributes are emulated on the NVT screen by the driver. The OIA indicates if the driver is disconnected (disc at the beginning of the OIA), in NVT mode (NVT) or in a TN3270 session (TA#). The Test key causes the driver to disconnect from the host and return to disconnected NVT mode.

pcMAINFRAME Express

Appendix A - Configuration for Commonly used Devices 79

Configuration for LU6.2 Connections

pcMAINFRAME Device Configuration -------WinCPIC LU6.2------Trace size in K bytes 0000 Connect timeout (seconds 0000 Default configuration key CICSPROD Configuration Records: Key Description CICSPROD PRODUCTION CICS

[To turn trace OFF, enter 0 as the size] [To turn trace ON, enter the number of K-bytes (from 4 to 63 to be allocated.] PgDn: Next Page PgUp: Prior Page F10: Write config to disk Esc: Exit

Figure 6-4: WinCPIC LU6.2 configuration panel 1

pcMAINFRAME Device Configuration -------WinCPIC LU6.2------Key CICSPROD Description LU Alias PLU Alias Mode Name PGM User ID Password PRODUCTION CICS USER1 PCICS MODELU62 USER0001

[Enter 1-16 character key to be used for this configuration record.] F10: Write config to disk Esc: Exit

Figure 6-5: WinCPIC LU6.2 configuration panel 2

These device drivers are used in environments where connection to the mainframe is via LU 6.2 protocol. The configuration panels for each of the LU6.2 drivers are similar to those above. MAINCON Configuration The configuration panels allow for general configuration information and up to eight configurations for connecting to the host. The panels should be completed as follows. Enter the value for Trace Bytes in K. 0 or 4-63 are valid entries. This should normally be 0 unless you are instructed by cfSOFTWARE to enable this option. The Connect Timeout is the amount of time to wait for a response to a connect request. The default configuration key is used to specify the configuration record to use when an application does not explicitly specify a key.

The bottom portion of panel 1 is a list of the keys of each configuration record defined. The fields cannot be entered directly, but are changed via panel 2. To access panel 2 fields, tab to a key field in the configuration list, then: Press F2 to add a new configuration record.

80 Appendix A - Configuration for Commonly used Devices

pcMAINFRAME Express

Press F3 to delete the selected configuration record. Press F4 to modify the selected configuration record. Press F5 to set the selected configuration record as the default.

Note: A default configuration must be specified. At least one configuration record must be defined. The panel 2 fields are as follows: LU alias (if defined) is the name of the Alias record in the LU6.2 stack for the local LU to be used for the LU6.2 connection. PLU alias is the name of the Alias record in the LU6.2 stack for host LU (APPLID) to connect to. Mode Name is the LU6.2 mode name, often (#INTER or #BATCH) to use for the connection. PGM - Leave blank. User ID is the user name to use for the LU6.2 conversation security. Password is the password to use for the LU6.2 conversation security.

LU 6.2 Configuration LU6.2 connections require mainframe (VTAM) as well as PC (emulator or gateway) configuration. Given the diversity of SNA networks and the many different LU6.2 network implementation options, this document does not include specifications for configuring your LU6.2 network. cfSOFTWARE technical support can provide general configuration and usage information for setting up LU6.2 connections for use with pcMAINFRAME Express. Please contact us for further information.

Video Mode and 3270 Keyboard Layout

pcMAINFRAME Device Configuration Page 1 of 3 ---------- VIDEO MONITOR MODE 0 = AUTO, 1 = BW80, 3 = IBM 3270PC...... 0 = fast mode, 1 = slow (well behaved).. Controller Language..................... Alternate key-scancode file suffix...... Alternate buffer-code file suffix....... Super VGA BIOS type..................... Choose desired video dimensions......... Cursor following........................ EABs requested?......................... Text-Translate-Table ID................. 0 0 1 0 0 Y N

[If color or monochrome setting is to be determined automatically, enter 0. To force black and white, enter 1. If using a 3270PC, enter 3] F10: write to disk PgDn: Keyboard layout F7: customize keys Esc: Exit

Figure 6-6: Video Mode

Configuration panel A1, Video Mode/Keyboard, is used to control how the display is written to, 3270 emulator language configuration and the 3270 keyboard mapping for Dialog. The default settings on page 1 are not normally changed, unless custom language or translation mode settings are desired

pcMAINFRAME Express

Appendix A - Configuration for Commonly used Devices 81

The Controller Language code is used to define the set of valid characters for 3270 emulators that are not configured for U.S. English. For CUT mode devices this table also defines the remapping of the non-U.S. English 3270 keyboard. If a Controller Language of 9 or * is selected, a custom configuration is created. To view the selected language set, or define a custom one, press  . The following controller languages are defined: 1 - U.S. English 2 - Dutch 3 - French AZERTY 4 - German 5 - Italian 6 - Spanish 7 - Brazilian 8 - U.K. English S - Finnish/Swedish H - U.S. English Hydra EABs Requested: Set to Y or N (default). If set to Y, EABs will be interpreted by Dialog. Text Translate Table ID: provides an alternate way of specifying which text-translate table pcMAINFRAME is to use. pcMAINFRAME users should usually specify the Text-Translate table ID in PCXSETUP as described in Chapter 3. Contact cfSOFTWARE if a problem requiring non-standard scan code or buffer code tables appears to be needed. Screens 2 and 3 of this configuration option allow the remapping of the keyboard. By default, the 3270 keys are represented on the PC keyboard in the manner displayed in the Default 3270 Keyboard Layout later in this section. These screens, shown below, contain columns of 3270 keys. Corresponding entries show the PC key that is used to indicate a 3270 function. For example, in the screen below, the ! key is mapped to the  9  key on the PC. When in terminal emulation mode, striking the  9  key will cause a ! key to be sent to the host.
pcMAINFRAME Device Configuration Page 2 of 3 PC Keys Representing 3270 Keys 3270 PC 3270 PC ENTER (Enter) PF16 Alt R PF1 Alt 1 PF17 Alt T PF2 Alt 2 PF18 Alt Y PF3 Alt 3 PF19 Alt U PF4 Alt 4 PF20 Alt I PF5 Alt 5 PF21 Alt O PF6 Alt 6 PF22 Alt P PF7 Alt 7 PF23 Alt A PF8 Alt 8 PF24 Alt S PF9 Alt 9 PA1 Alt J PF10 Alt 0 PA2 Alt K PF11 Alt PA3 Alt L PF12 Alt = CLEAR F2 PF13 Alt Q SYSREQ Alt F1 PF14 Alt W TEST Alt F8 PF15 Alt E ATTN F1 Use keys to position. Press to select a key for change F10:write config Esc:Exit PgDn:next page PgUp:prior page F1:help F2: toggle gray-keys same/different - SAME F3: 5250 keys

Figure 6-7: Keyboard Layout

The



key brings up a help screen that describes the entry of data into these screens.

82 Appendix A - Configuration for Commonly used Devices

pcMAINFRAME Express

PF1
Tab

PF2

PF3

PF4

PF5

PF6

PF7

PF8

PF9

PF10

PF11
{ [

pcMAINFRAME Express
`

F1

F2

F3

F4

F5 ErEOF

F6

F7

F8

F9

F10 Reset DvCnl

F11

F12

Esc

Attn SysReq

Clear
CurSel

ErInp

Print Ident

Click Test

Print Screen

Scroll Lock

Pause

AltCr

! 1

@ 2

# 3

$ 4

% 5

^ 6

& 7

* 8

( 9

) 0 _

+ =

Backspace

Ins

Home

^ a

PgUp

Num Lock

PF12
} ] | \

Q
PF13

W
PF14

E
PF15

R
PF16

T
PF17

Y
PF18

U
PF19

I
PF20

O
PF21

P
PF22
: ;

Del

7
End PgDn

9
+

Caps Lock

A
PF23

S
PF24

G
Dup

H
Mark

J
PA1

K
PA2

L
PA3
< , > .

" '

4
Enter

Shift

? /

Shift

*
1 2 3
Enter

Appendix A - Configuration for Commonly used Devices 83

Ctrl

Alt

Alt

Ctrl

*
Ctrl Alt

Ctrl + key

Alt + key

Default 3270 Keyboard Layout

May be modified in MAINCON. Configuration Panel A1.

Communications Device List

The Communications Device List defined below is a summary of all supported devices for pcMAINFRAME Express.

CUT Mode 3278/79 Cards

If your device is not listed, call cfSOFTWARE at: (847) 824-7180. IBM 3270 Card in CUT mode IRMA, IRMA2, IRMA3 CUT mode Forte in CUT mode Xircom Pocket 3270

16 Bit Windows Emulators

Attachmate EXTRA! for Windows DYNACOMM Elite Eicon for Windows IBM Personal Communications for Windows IBM Personal Communications for Windows non-SF ICOT Omnipath for Windows IRMA Workstation for Windows Memorex-Telex 1472 for Windows Novell LAN Workstation/Windows Rumba for Windows Windows WOSA HLLAPI

32 Bit Emulators
Attachmate Extra! Win32 for NT/95 HLLAPI (WOSA) Win 32 NetManage Swift for Win32 NS/Elite Plus for Win32 Personal Communications for 95/NT Personal Communications for 95/NT-SF Rumba for Windows NT WRQ Reflection for IBM Win32

TCP/IP Connections
TCP Direct - APPX Listener TN3270 Chameleon/Newt TN3270 FTP PC/TCP TN3270 PC/NFS TN3270 LAN Workplace

84 Appendix A - Configuration for Commonly used Devices

pcMAINFRAME Express

TN3270 Windows Sockets TN3270 Win32 Sockets

LU 6.2 Connections
LU 6.2 Extra! For Win32 LU 6.2 Personal Communications for Win32 Rumba for Win32 WinCPIC for Win32

pcMAINFRAME Express

Appendix A - Configuration for Commonly used Devices 85

86 Appendix A - Configuration for Commonly used Devices

pcMAINFRAME Express

Appendix B - Custom Translate Tables

pcMAINFRAME Express provides a means of customizing the translation of characters between ASCII on the PC and EBCDIC on the mainframe. This facility is implemented through the definition and specification of translate tables. The translate tables are created on the PC with a program called MAINXLAT. This is provided with the pcMAINFRAME Express distribution materials and is located in the main pcMAINFRAME Express directory if alternate language support was requested at installation time on the PC. The use of the custom translate table is controlled by options specified with the program MAINCON. The considerations for defining and using custom translate tables are discussed in the sections that follow.

Defining Custom Translate Tables

pcMAINFRAME Express provides a program called MAINXLAT that builds and modifies the custom translate tables. There are several model tables distributed with Express. They may be found in the same directory in which pcMAINFRAME Express was installed. Tables are stored with filenames in the form of mainxlat.txn, where n is the table identifier suffix. The supplied tables are: mainxlat.tx2 Dutch mainxlat.tx3 French Azerty mainxlat.tx4 German mainxlat.tx5 Italian mainxlat.tx6 Spanish mainxlat.tx7 Brazilian Portuguese mainxlat.tx8 U.K. English mainxlat.txS Swedish/Finnish mainxlat.txA Danish/Norwegian Alternate mainxlat.txB Finnish/Swedish Alternate

pcMAINFRAME Express

Appendix B - Custom Translate Tables 87

These may be used as is or may be used as a starting point and modified to meet your particular requirements. To create or modify a translate table, invoke the program MAINXLAT. The figure below is an image of the initial screen presented by MAINXLAT.

pcMAINFRAME EXPRESS - Special Text Translate Table

Xlat file Options: View Edit Save saveAs Cancel Quit

View text translate file

File path: Text Translate Table ID:

Enter=Select

Esc=Quit

Figure B-1: MAINXLAT Initial Menu

From this menu, the appropriate function must be selected. The view option allows the review of a table without update. The edit option allows a new table to be built or an existing table altered. Both of these options require that a path and table suffix be entered to identify the table to be used. This entry is shown in the figure below. The other options allow you to save the current table. Any changes made will be stored. The saveAs option permits the renaming of a table before saving. The cancel option is used to drop the current table and force access to a different table. Quit exits the program.

pcMAINFRAME EXPRESS - Special Text Translate Table

Xlat file Options: View Edit Save saveAs Cancel Quit

View text translate file

File path:

G:\PCM4\TEST

Text Translate Table ID: 3 (MAINXLAT.TX3)

Enter=Select

Esc=Quit

Figure B-2: MAINXLAT File Selection

88 Appendix B - Custom Translate Tables

pcMAINFRAME Express

Once a table is selected for view or edit, a display like the one below appears. There are two portions to each table: the ASCII to EBCDIC portion and the EBCDIC to ASCII portion. Each portion has several screens. You may move from one screen to another by pressing the ! &5 and ! 3 keys. You may move from one line to the next by pressing the D and E keys. You may alternate between the ASCII to EBCDIC and EBCDIC to ASCII by pressing the  key.

pcMAINFRAME EXPRESS - Special Text Translate Table

Xlat file Options: View Edit Save saveAs Cancel Quit

View text translate file

File name:

G:\PCM4\TEST\MAINXLAT.TX3 ASCII to EBCDIC Invalid Character ID: 00 Character CHAR: p q r s t u v w x y z ASCII: 70 71 72 73 74 75 76 77 78 79 7A EBCDIC: 97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 CHAR: ASCII: EBCDIC: CHAR: ASCII: EBCDIC: 80 00 90 00

70 { 7B 51

thru 9F | } n 7C 7D 7E 7F 00 54 BD 00

81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F DC C0 42 43 7C 00 E0 52 53 D0 57 56 00 00 00 f 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F 00 00 CB CC 00 DB 6A DF 00 00 00 7B 00 00 00

Enter HEX value of EBCDIC character

PgUp/PgDn

F3=End

F4=Sync-up Tables

F8=Switch Tables

Esc=Return

Figure B-3: MAINXLAT Table Editing

Characters that may be altered are highlighted. Certain characters, such as upper and lower case A - Z, are not modifiable. In order to save time and insure symmetry, the  key will copy the current table to the alternate table. For example, if you have created the ASCII to EBCDIC portion of the table, pressing  will build the EBCDIC to ASCII portion of the table with the mirror translations as the ASCII to EBCDIC portion that you entered. If you are in the EBCDIC to ASCII portion of the table when you press  , it will build the ASCII to EBCDIC portion. Make certain that you are in the correct portion of the table when you use this function or you could overlay your work with inappropriate values.

The  key exits the table display and returns you to the main menu. From the main menu select the save or saveAs option to save the table.

pcMAINFRAME Express

Appendix B - Custom Translate Tables 89

Selecting a Custom Translate Table for Use

Once a table has been defined, it must be specified for use. This is done through the use of the program MAINCON. From the main menu, select option A1, Video Monitor Mode and 3270/5250 Keyboard. This will bring up the configuration screen shown below.

pcMAINFRAME EXPRESS Device Configuration Page 1 of 3 ----------VIDEO MONITOR MODE---------0 = AUTO, 1 = BW80, 3 = IBM 3270PC ............ 0 0 = fast mode, 1 = slow (well behaved) ........ 0 Controller Language ........................... 1 Alternate key-scancode file suffix ............ Alternate buffer-code file suffix ............. Super VGA BIOS type ........................... 0 Choose desired video dimensions ............... 0 Cursor following .............................. Y EABs requested?. .............................. N Text-Translate-Table ID ....................... _ [If a special text-translate-table for data transfer is needed, enter the one character ID X of the name of the table file (mainxlat.txX).] F10: write config to disk Esc: Exit PgDn: config keyboard layout

Figure B-4: MAINCON Option A1 Screen

Specify the suffix of the table that you wish to use by placing the one character table suffix on the line identified as Text-Translate-Table ID. Save the configuration by pressing the  key.

90 Appendix B - Custom Translate Tables

pcMAINFRAME Express

Index
A
Advanced Parms Screen 52, 5152 Buffer 52 Translation Table 52 APPX TPNS Configuraion 43 Event Viewer 59 PC Installation 38 Service Manager 57 Start TPN Services 45 Audit Files 16 Connect Parameter AUDIT 21 AUDITID 21 Format Basic 16 Fixed 16 Log 16 JCL Example MVS 30 VSE 27 JCL Requirements MVS 27 VSE 26 Record Definition 17

B
Block Size 23 Buffer 52

C
CFXATB.INI 56 Command File 1925 Format 20 Parameter Descriptions Connect 21 File Transfer 23 PCSCRIPT Statements 25 Compression Connect Parameter DCOPTION/UCOPTION 21 Setup File 52 Connection Verification 43

pcMAINFRAME Express

Index 91

D
Device 50 Defined in Setup file 50

E
Edit Text Option 49 Emulation 42 Encryption 49 of Setup File 49 Epilog 47, 48, 55 eText Option 49

F
File Transfer JCL Requirements MVS 27 VSE 26 JCL Sample MVS 30 VSE 27, 28 Parameters 23

H
Host Wait State 42, 43, 47, 64

I
Installation APPX TPNS 38 Mainframe 5, 711 PC 5, 3538, 35 VTAM Definitions 8

J
JCL MVS Control Language Requirements 27 Examples 30 Installation Verification 13 VSE Control Language Requirements 26 Examples 27 Installation Verification 12 Library Merge 7

92 Index

pcMAINFRAME Express

Library Restore 7

L
Language Support 48 LU6.2 52, 55 Connect Parameter LU62 22 LU62PASS 22 LU62USER 22

M
Main Transfer Window 46 Mainxlat 8790

O
Options Screen 48 Overview 3

P
Parameter Screen 48, 5051 Advanced Parms see Advanced Parms Screen Communications Device 50 Description 50 Host Session 50 Run Mode 50 Trouble Shooting 50 PC Log Sample 47 Setup file setting 51 Target Directory setting 51 PC Start Up LU2 (3270) connections 41 LU6.2 connections 45 TCP/IP connections 43 PCSCRIPT Capabilities 17 Command File Format 25 Download Example 10 MVS JCL Examples 31 Return Code Testing 18 Upload Example 10 VSE JCL Examples 28 PCXSETUP Advanced Parms Screen 52 Menu File 49

pcMAINFRAME Express

Index 93

Options 49 Parameter Screen 5051 Prolog 48, 55

R
Reports 25 Control Report 25 Transfer Report 25, 26 Return Codes 1819 Testing 1819, 23 Values LASTRC 19 MAXRC 18 USERRC 19

S
Setup File General Rules 54 Layout 54 Options 48 Parameters 48 Variable: 55 Side Info 52, 55 SNA Multiple Domain Networks 10 Terminal LUs 9

T
TCP/IP Connect Parameter HOST 22 PORT 22 SUBSYSID 22 TCPIP 22 TCPNAME 22 TPN 22 TCP/IP Direct 52, 55 Terminal Emulation 42 Trace Connect Parameter TRACE 22 Transfer Processing 46 Translate Table 8790 Custom tables 8790 Translation Table 52 Troubleshooting 6173

94 Index

pcMAINFRAME Express

V
VTAM Connect Messages 67 Connect Parameter APPLID 21 APPLPASS 21 LUNAME 22 RETRY 22 Connect Parameters APPLCOUNT 21 Definitions 810 APPL IDs 8 LU6.2 10 SNA Networks 10 Terminal LUs 9

pcMAINFRAME Express

Index 95