#if defined(W32) || defined(LNX)
.Turnkey MVS support.
It is available to download,update then upload the file on Hercules + MVS-R38J.
"Turnkey MVS" is MVSR38J on PC("Hercules" emulates 370 instruction).
(0) Prerequisite
#ifdef LNX
You have to install s3270.
Or,if you use x3270,install x3270 and setup xe3270.cfg to use x3270.
#else
This function use "s3270.exe" which runs under cygwin.
You have to install cygwin and s3270.
Or,if you use x3270,install x3270 and setup xe3270.cfg to use x3270.
And you need to start X-server process before use xe3270 start
when x3270 is used.(or else xe3270 fails by "Pipe Closed" or "TimeOut")
#endif
When x3270 is used,you can see the x3270 screen,but xe loose the focus
in some linux version. In that case you may minimize the x3270 window.
You have to install also IND$FILE to Turnkey MVS.
Warning:ind$file106 returns "TRANS00file not opened" if HostFile D/S or member dose not exist,
but ind$file111 wait infinitely.
xe confirm the existance by LISTDS command in order to avoid infinite wait.
You may configure firewall if Hercules is remote system.
At first,It is better to do connection test using simply s3270 as following.
.start s3270 with no operand after MVS started.
.enter 'connect hostname:3270' (hostname is "localhost" etc.)
status line changed to indicate connected (4th char='C')?
'ascii' command is used to see current screen.
you can see logon prompt scree?
.enter 'String "logon herc02/cul8tr\n"' to logon.
.try FTP by 'Transfer Direction=get HostFile=xxxx(yyy) LocalFile=zzz Exist=replace' etc.
(1) Setup for xe.
.Define destination ID on "::xehosts" file(xehosts in xe's working directory).
ex) herc01 Heaven HERC01 "" TSO=3270
h02 192.168.2.33 HERC02 password TSO=3270 HOME='herc01.test.src'
"TSO=" means target is 3270 and opearnd "3270" specify port number.
If missing "TSO=xxxx", target is tcpip:ftp remote.
Host-id(first item) for TSO is case insensitive.
Password is encrypted when saved.
.configure xe3270.cfg
This file is used to change the default,
especialy to manipulate SPF information specify both SPF_LEVEL and CMD_MEMBLIST.
The holding directory is specified by /W command line parameter of xe3270.
When xe3270 is automaticaly started by xe that is workdir of xe(::xe3270.cfg).
Ex). ("#" on the top of line means comment line)
#####################################################################
# xe3270.cfg
# CMD3270 :cmd to call 3270
# default is s3270
# To use x3270(-script option is required for xe)
# Windows example
# CMD3270 = "bash c:\x3270script"
# c:\x3270script contents is as following
# DISPLAY=:0.0 x3270 -script
# Linux example
# CMD3270 = "x3270 -script"
# RETRY_UPLOAD :read-check retry count when read check after put failed.
# Max:4 Min:0 Default:2
# RETRY_DOWNLOAD :read retry count when dual read unmatch
# Max:4 Min:0 Default:2
# SPF_LEVEL :process level of SPF information
# 0:CMD_MEMBLIST is not used.
# 1:SPF info is displayed on dir-list using XE4S001Z
# 2:SPF info is maintenanced using XE4S001Z
# default is 0 without CMD_MEMBLIST or 2 with CMD_MEMLIST specified
# CMD_MEMBLIST :TSO command to get PDS memberlist
# Default is TSO native "LISTDS" command
# Specify you LibraryDataSet name if you use XE4S001Z prepared by xe package.
# PS_UPLOAD :Allow DSNAME as upload target
# 1:allow 0:prohibit(default)
# "1" may accidentaly cause corruption of PDS directory.
# TIMEOUT_CONNECT:timeout to get 3270 connection by seconds
# commandline parm -C override this cfg parm
# -1:infinite, default=10
# TIMEOUT_FTP :timeout to file Send/Receive
# commandline parm -T override this cfg parm
# -1:infinite(default)
# TIMEOUT_TSOCMD :timeout to file Send/Receive
# -1:infinite, default=30
# sample
# RETRY_UPLOAD = 1
# CMD_MEMBLIST = "call 'herc01.load.asm(xe4s001z)'"
#####################################################################
#CMD3270 = s3270
#CMD3270 = "x3270 -script"
#CMD3270 = "bash g:\src\xe\x1x3270s"
RETRY_UPLOAD = 2
RETRY_DOWNLOAD = 2
SPF_LEVEL = 2
CMD_MEMBLIST = "call 'sak01.load.asm(xe4s001z)'"
PS_UPLOAD = 1
#TIMEOUT_CONNECT = 20
#TIMEOUT_FTP = 600
#TIMEOUT_TSOCMD = 60
#####################################################################
.Install XE4S001Z
XE4s001Z is required if you want to display SPF information
(userid,timestamp,line count) on dir-list
and to update after edit.
Assemble XE4S001Z the put LoadModule to a Library.
The configure CMD_MEMBLIST parameter of xe3270.cfg.
Referencing MACLIB is as follows.
// EXEC PGM=IGOX00,PARM='...,SYSPARM=NOSNAP',...
//SYSLIB DD DSN=SYS2.MACLIB,DISP=SHR
// DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=SYS1.AMODGEN,DISP=SHR
(SYSPARM=NOSNAP is required to make ULSNAP debug macro to NOP)
If upload LoadModule in the ZIP file as alternative of assemble,
fowllowings are the procedure to install from aws tape format file.
- Set tape device to online.
Enter "V 480,ONLINE" on MVS-Console.
- Submit XE4S001Z.jcl using sub tool of Tunkey-MVS in scripts dir
or use SUB TSO command after uploading by 3270 FTP.
You should modify the jcl before submit.
Change dataset name of //DD2 to your own.
(LoadModule BLKSIZE=19069).
- Reply to tape mount request.
Enter "devinit 480 (path)XE4S001Z.aws" on Hercules Console.
(path) is the place of the aws file on your PC.
(2) Specify TSO destination id on Edit/Browse command etc.
ex) e h02:'herc01.source.asm(memb1)'
e herc01:source.asm(memb1)
At first access to TSO,"xe3270.exe" is started which help comunication
between xe and 3270 emulator.
#ifdef LNX
Terminal emulator on which xe3270 start is set by ini file.
Default is determined by searching gnome-terminal,konsole and xterm in this sequence.
#endif
NamedPipe with multiple instances is used to comunicate with xe.
Thread starts for each target(system + TSO-UserID) and communicate with
3270 emulator process by stdid/stdout redirection pipe.
This allows that multiple xe use same TSO-UserID and one xe session use
multiple TSO-UserID.
Even after xe ended, xe3270.exe remains active and wait next request from xe.
You can check the status in DOS-prompt window of xe3270.exe.
Optionaly(/F parm of xe) those are logged in "::xe3270.log" file.
New command "TSO" supports to handle communication trouble.
You can switch the =6 panel to TSO mode. In TSO mode native MVS TSO command
such as "listalc" is entered without xe TSO command prefix.
Logoff command swithes back to local command mode.
In TSO mode local command can be entered by prefixing ":"
For example,":grep ABC *.c".
Same command but different syntax can be entered through xe3270 DOS prompt screen,
use it when xe is hunged waiting response from xe3270.
(3) Trouble handling.
.When Hercule/MVS is not yet started.
#ifdef LNX
"port 3270:Connection refused."
"Connection rejected, no available 3270 device" if Hercules started.
#else //Windows
Connection wait until response returns with 10sec timeout.
#endif
.When 3270 device is not ready.
Connection wait until response returns with 10sec timeout.
---> Activate from MVS console.
V NET,INACT,ID=CUU0Cx,I
V NET,ACT,ID=CUU0Cx
You can enter these command using PF2.(Check it by "D PFK")
.When reached to maximum 3270 session count.
"no available 3270 device"
--->close one of opened TSO(3270 emulator) session to yield to xe.
Or,run "setupterm" to increase device count.
"startterm" defines intial start session count,and
SYS1.VTAMLST defines terminal initialy activated.
.When TSO is not active.
"APPLICATION IS INACTIVE"
--->"S TSO" from MVS console
.When invalid TSO-UserID used.
"INPUT NOT RECOGNIZED"
--->Correct definition in ::xehost file then retry.
.When invalid Passoword used.
"PASSWORD NOT AUTOLIZED FOR USERID REENTER -"
--->Enter "TSO reply hostid valid-password" command.
::xehosts file would be corrected.
"TSO cancel hostid" may be alternative to retry Edit command.
You can see the current screen status by "snap" command on
xe3270.exe DOS prompt screen.
.When duplicated UserID logon.
"IKJ56425I LOGON REJECTED, USERID xxxx INUSE"
--->"logoff" is issues internaly.
"C U=xxxx" on mvs console immediately release the UserID
who is interrupted.
.When HostFile not found
ind$file v106 returns FILE00. Other version may cause infinite wait.
See MVS console to chk ABEND S013 etc.
If wait,enter "cancel" or "quit" command to xe3270 command prompt.
.When timeout received.
Connection timeout is set to 10 seconds,Transfer timeout is infinite.
When ABEND such as x37 occued,xe wait resonse infinitly.
Check it on MVS console then enter cancel command on xe3270 DOS prompt screen.
Even when timeout msg is retuned,thread may waiting 3270 response.
Until 3270 returns resonse thread is busy and is not available to accept cmd.
To reset and reuse the timeouted busy thread use also cancel command.
xe command "TSO cancel hostid" is available when timeout case.
If save failed,xe dose not end itself. Save temporaly to local file
then exit xe. Later you may restore to original destination.
(4) Other miscellaneous.
.TSO file is opened with option CAP ON as default.
To deny it use [CAP|NOCAP] option of Edit command
or change the default by CAP command.
To enter lowercase letter when CAP ON,use Shift key.
.E/B command is treated as EN/BN for the file with RECFM=Fx,LRECL=80 on turnkey-MVS.
For COBOL file,'N' is yet required like as ECN to maintenance automaticaly line number field.
Alias command function allow to abbreviate optional parameter specification
such as /P1(protect col.73-80 field).
For the file col.73-80 is not line-number but a part of data,it is convenient
to specify f80 option to open. You may use e8 command as alternative.
No conversion is done when upload/download if opend by binary mode
(EB,EH command).
/B option of Copy/Move/Append command support file transfer with no translation
of EBCDIC and ASCII.
.Filename referencing function corresponds to MVS file naming convention.
*\ --> *. **\ --> **. ^*\ --> ^*.
ex) "e *(m2)" opens h01:'a.b.c(m2)' on the screen opened h01:'a.b.c(m1)',
**.d(m3) means h01:'a.b.d(m3)'.
"e ^*(m2)" on the 2nd panel opens h01:'a.b.c(m2)' when h01:'a.b.c(m1)'
is opend on the 1st panel of the split screen,
^*.**(m4) means h01:'a.b(m4)'.
JCL submitting is available using sub.bat provided by Turnkey MVS.
Call sub.bat from xe's SUB command.(place sub.bat on proper PATH).
On the panel JCL file is opend,enter simply "SUB".
On the panel local file is opened,enter "SUB sub *".
Alias command may be used for abbreviation.
for example,after defined "Alias:JCL SUB sub.bat *" on =0.1 panel,
"JCL" cmd submit the local file to TSO.
If you want to use "SUB" to submit to TSO,you have to change
the command verb of submit function on ini file,then define
"SUB" as alias command.
To submit from dir-list,use "#" line cmd. Input on rename field
is ignored. When using "%" lcmd,enter "sub"(tool name prepared
by Turnkey-MVS) on rename field.
.About SPF information.
By specifying SPF_LEVEL and CMD_MEMBLIST on xe3270.cfg,
SPF information is displayed on dir-list panel for the PDS member
with RECFM=Fx and LRECL=80.
To display line count or files size is toggled by F6 key.
For SPF file line count is initialy displayed.
Use S+F6 to display USERID.
xe keeps the SPF information dropped by uploading by IND$FILE.
And MM(modification level) is updated as following.
If the menber's COL73-80 is valid line-number, max value of COL79-80
is assumed as MM value of the member.
When the member update session end,the MM+1 is back to the PDS direcytory.
If the other member is replaced by Save/Replace command,the MM value is
set to that member. When copy source has no SPF information such as PC file
or when append to that member,target members MM is 1 up.
By XCOpy command SPF info is copyed,by XAPpend command target MM is 1 up.
"a" line command is used to update Version and Modification level of the member.
SPF subcommand of xe's TSO command may be used to update SPF info of
whole(WILDCARD "*"/"?" is also supported) member of the PDS.
For ex.,use it to set SPF info at once for the PDS with no SPF info.
Line count is gotten by reading the member.
(RPF may require CreationDate,LastUpdateDate,Userid to display on the PDS list)
To execute XE4S001Z as batch job,refer the following description to specify parameter.
(copyed from header part of source file XE4S001Z)
*(2)* UPDATE SPF INFORMATION ON PDS DIRECTORY ********************* 00330030
* PARM FORMAT 00340030
* '1,DSN(MEMB),VV,MM,CDATE,UDATE,UTIME,CURLINE,INITLINE,USER' 00350035
* 00360034
* (START BY NOT NUMERIC MEANS MISSING OPERAND EXCEPT FOR USERID) 00370034
* (!!! RPF(V153) NEED CRE-DATE/UP-DATE/USERID TO DISPLY ON DIRLIST) 00380039
* 00390034
* 1:FUNCTION ID:UPDATE SPF INFO 00400030
* MEMB:REQUIRE. WILDCARD('*' or '?') IS AVAILABLE. 00410030
* VV:VERSION 00410030
* IF MISSING,KEEP CURRENT VALUE OR SET 0 IF NO PREVIOUS INFO 00420034
* +N FORMAT IS USED TO INCREMENT 00430030
* MM:MODIFICATION LEVEL 00440030
* IF MISSING,KEEP CURRENT VALUE OR SET 0 IF NO PREVIOUS INFO 00450034
* +N FORMAT IS USED TO INCREMENT 00460030
* 'NOW' IS USED TO SET TO MAX VALUE OF COLUMN 79-80 00470038
* CDATE:CREATED DATE 00480030
* IF MISSING,KEEP CURRENT VALUE OR SET 0 IF NO PREVIOUS INFO 00490039
* 'NOW' IS USED TO SET TO TODAY 00500034
* '000000' IS USED TO SET TO 0 00510039
* UDATE:LAST UPDATED DATE 00520030
* IF MISSING,KEEP CURRENT VALUE OR SET 0 IF NO PREVIOUS INFO 00530039
* 'NOW' IS USED TO SET TO TODAY 00540030
* '000000' IS USED TO SET TO 0 00550039
* UTIME:LAST UPDATED TIME 00560030
* IF MISSING,KEEP CURRENT VALUE OR SET 0 IF NO PREVIOUS INFO 00570039
* 'NOW' IS USED TO SET TO CURRENT TIME 00580031
* CURLINE:CURRENT LINE COUNT 00590031
* IF MISSING,KEEP CURRENT VALUE OR SET 0 IF NO PREVIOUS INFO 00600033
* 'NOW' IS USED TO SET CURRENT LINE COUNT BY READING MEMBER 00610034
* INITLINE:INITIAL LINE COUNT 00620035
* IF MISSING,KEEP CURRENT VALUE OR SET 0 IF NO PREVIOUS INFO. 00630035
* 'NOW' IS USED TO SET CURRENT LINE COUNT BY READING MEMBER 00640035
* USER :LAST UPDATED USER 00650031
* IF MISSING,KEEP CURRENT VALUE OR SET BLANK IF NO PREVIOUS INFO 00660031
*SAMPLE JCL TO EXECUTE BATCH * 00670031
*//GO EXEC PGM=XE4S001Z,PARM=('1','HERC01.SOURCE.ASM(MEMB),', 00680033
*// '01,21,061105,061125,2210,99,101,HERC01') 00690031
*//GO EXEC PGM=XE4S001Z,PARM=('1','HERC01.SOURCE.ASM(MEMB),', 00700033
*// 'VV,+1,CDT,NOW,NOW,CLC,NOW,HERC01') 00710035
*//GO EXEC PGM=XE4S001Z,PARM='1,HERC01.SOURCE.ASM(MEMB),DEL' 00720035
*//STEPLIB DD DISP=SHR,DSN=HERC01.LOAD.ASM 00730031
(5) Limitation and Warning.
!! .To update PDS directory,the dataset should be allocated exclusively.
(currentry XE4S001z use DISP=OLD and dose not use RESERVE macro)
Try again after closing RPF session.
.Upload is for PDS member only as default.
Specify PS_UPLOAD parameter of xe3270.cfg to do it.
.Long lines are split when upload to the file with RECFM=F(B).
When uploading by binary mode,null char is appended to fill the
line up to the record length if RECFM=Fx.
!! .I do not know the reason but file transfer sometimes miss,duplication
or lack, some amount (it may be 24*76=1844) of lines.
So,xe3270 download twice for get request from xe and if both is same
returns "success". If unmatch is detected,retry until the count
specified by xe3270.cfg exausted.
(retry will be stopped by Timeout)
If the retry count exausted,the file for investigation is left in the
temp dir(TEMP environment variable for Windows or /tmp for Linux).
Those file nameing is xe3270pc.xxxxxxxx.GETn.y.(xxxxxxxx:Membername)
Usualy you may retry the download request.
For the case whole PDS download by xcopy command is interrupted,
you may continue the xcopy adding /y- (skip the existing file) option.
For put request from xe,xe3270 confirm the output by re-downloading
after upload.(When binary mode,Null character appending is checked and
allow it as successfull and the fact is displayed on the xe3270 DOS-prompt.
And optionaly logged)
If 2 file is unmatch,Send&Receive are retried by the count specified at xe3270.cfg.
If retry count is exausted,the file for investigation are left on
temp dir. Those file nameing is xe3270pc.xxxxxxxx.PUTGETn.y.(xxxxxxxx:Membername)
If put request is of save of file edit,save is rejected but
contents are save on workdir(::xeftpwd) by the naming of
xxxxxxxx.timestamp even after you canceled save.
Usualy you may retry to upload request except following case.
IND$FILE split long line when upload to fixed LRECL dataset.
xe issue warning on xe3270 prompt screen and beep twice when detected split line,
and upload is assumed as completed.
If the file contains the chracter which is not commutative for
conversion between EBCDIC and ASCII.
!! .Downloaded file is not locked.
Before upload xe download again then compare it with the file save at
previous downloaded time. Waring is issued if those are not same.
Even when the file is opened by RPF,upload is not prevented.
And RPF cannot detect the file is downloaded,so the uploaded
may be overrided by RPF save operation.
(Between RPF,same Member is not opend by the reason of in-use)
xe provides "TSO Alloc/Free" command.
If unmatch detected,both files are kept on work-dir(::xeftpwd)
by the naming of xxxxxxxx.timestamp and xxxxxxxx.timestamp.UPDATECHK
but you should save current update to another file.
#endif