HP StorageWorks P9000 Data Exchange User Guide Part Number: T1620-96016 First edition: October 2010
Legal and notice information © Copyright 2007, 2010 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice.
Contents 1 Overview of HP StorageWorks Data Exchange Software ....................... 13 2 About Data Exchange Operations ...................................................... 15 Components ............................................................................................................................ Data Exchange Volume Types .............................................................................................. AIX Installations ........................................................
Interval Function for OtM Transfer Completion (Linux) ..................................................................... 46 Environment Variable for Interval Time ................................................................................... 48 Display Window for Interval Function .................................................................................... 48 3 Preparing for Data Exchange Operations ............................................ 49 System Requirements ........................
Performing File Transfer Operations (UNIX) .......................................................................... Using the listvol Function (UNIX) ......................................................................................... Creating FCU Parameter Definition Files (UNIX) .................................................................... Creating Multiple Volume Definition Files (UNIX) ..................................................................
HP Technical Support .............................................................................................................. Subscription Service ................................................................................................................ HP Websites .......................................................................................................................... Documentation Feedback ........................................................................................
Figures 1 FXmto and FXotm System Configuration ..................................................................... 16 2 FXoto System Configuration ...................................................................................... 16 3 3390-3A/9A/LA Volume Structure (FXmto, FXotm, FXoto) ............................................ 17 4 3390-3B/9B/LB Volume Structure (FXmto) .................................................................. 18 5 3390-3C/9C/LC, 3380-KC/3C Volume Structure (FXotm) ......
33 Data Exchange Volume Definition File for NCR UNIX ................................................... 74 34 Data Exchange Volume Definition File for DYNIX/ptx ................................................... 74 35 Data Exchange Volume Definition File for Linux ........................................................... 75 36 ALC Utility for Windows Systems ............................................................................... 79 37 ALC Disk Not Found Message ..................................
70 Using the -nc Option ............................................................................................. 114 71 Using the -P param Option ..................................................................................... 114 72 FCU Version and Copyright Screen (Windows Systems) ............................................. 116 73 Execute Panel Showing Normal End ........................................................................ 118 74 Execute Panel Showing Canceled Operation ..........
Tables 1 Default EBCDIC-ASCII CC Table for FCU .................................................................... 21 2 User-Defined CC Table ............................................................................................ 22 3 FXmto Record Format Requirements ........................................................................... 27 4 Multiple Volume Dataset/Serial Numbers ................................................................... 31 5 FXotm Record Format Requirements ............
33 Partition Sizes for Storage Systems ............................................................................. 58 34 Sharing Data Exchange Volumes between Open-System Platforms ................................. 59 35 FMT Utility Values ................................................................................................... 67 36 Relation between Block Length and Write Available Capacity per Track ......................... 67 37 Data Exchange Volume Association Parameters ...................
1 Overview of HP StorageWorks Data Exchange Software Data Exchange enables data stored on the storage system to be converted and transferred between mainframe and open-system platforms and between different open-system platforms. • The FXmto capability enables you to transfer data from mainframe datasets to open-system files. • The FXotm capability enables you to transfer data from open-system files to mainframe datasets.
Overview of HP StorageWorks Data Exchange Software
2 About Data Exchange Operations This chapter describes how Data Exchange operates in typical system configurations and describes the operations a user may perform using Data Exchange.
Figure 1 FXmto and FXotm System Configuration . Figure 2 FXoto System Configuration .
The FCU program provides the commands and GUI for Data Exchange file transfer operations as well as several important options for data exchange, including EBCDIC-ASCII code conversion and data record padding and delimiters. The FAL is a library of C functions (Visual C++), which provides an application programming interface for data exchange. The FAL functions can be called by user application programs to read and write data in mainframe datasets on the storage systems.
Figure 4 3390-3B/9B/LB Volume Structure (FXmto) . NOTE: The open-system host accesses only the VTOC area on -B volumes. Catalog or security control functions cannot be used to provide access control for these volumes. • FXotm. The Data Exchange -C volumes can only be used for FXotm operations. Open-system hosts have read/write access to the -C volumes, but must use Data Exchange to access these volumes as raw devices (no mount operation). Mainframe hosts have read-only access to the -C volumes.
Figure 6 OPEN-x FMT Volume Structure (FXoto) . NOTE: When the mainframe OS is VSE, DFSORT cannot be used after a Data Exchange volume is copied to another volume. Use the DITTO function for this purpose. AIX Installations When installing Data Exchange devices in an AIX environment, the following notes apply: • When the UserID is not the root, a patch is required. • AIX V5.1 can be used with 64-bit FAL. Contact your IBM technical representative for assistance.
CAUTION: Do not write a signature on Data Exchange volumes having emulation types 3390-3X, 3390-9X, 3390-LX, 3380-KX, or 3380-3X (X = A, B, C) in a Windows environment. If a signature-writing attempt is made by the Disk Administrator with Windows, a Write Error will appear in order to stop the signature from being written. When the Windows Disk Administrator starts again, a request will be made again to write the signature. Do not write the signature.
NOTE: The default EBCDIC-ASCII CC table is the ACM standard table (not CACM). Appendix A on page 173 provides the code conversion information for the default table shown in Table 1 on page 21. If the default CC table does not yield the desired results, create your own CC table. See the IBM code tables for detailed information on EBCDIC-ASCII CC.
H L 0 1 FF IFS (0C) (1C) CR 2 3 4 5 6 7 DC4 < * % @ (8C) (14) (3C) (2A) (25) (40) IGS ENQ NAK ( ) _ ’ (0D) (1D) (05) (15) (28) (29) (5F) (27) SO IRS ACK + ; > = (0E) (1E) (06) (9E) (2B) (3B) (3E) (3D) SI IUS BEL SUB | ~ ? “ (0F) (1F) (07) (1A) (7C) (7E) (3F) (22) 8 9 A B C D E F (C6) (CD) (D4) (E4) (EA) (F0) (F6) (FC) [ ] C D (C7) (CE) (5B) (5D) (EB) (F1) (F7) (FD) (C8) (CF) (D6) (E6) (EC) (F2) (F8) (FE)
connect parent/child processes (with some exceptions). Named pipes are strictly unidirectional, even on systems where anonymous pipes are bidirectional (full-duplex). Using the PIPE function in UNIX Systems A named pipe is a special file that is used to transfer data between unrelated processes. One or more processes write to it, while another process reads from it. Named pipes are visible in the file system and may be viewed with ls like any other file. (Named pipes are also called FIFOs.
• Add WAIT_TIME_VALUE=300 • Add export WAIT_TIME_VALUE These two commands must be added to the file .dtprofile in the home directory. If .dtprofile does not exist, create it and add the lines. Figure 7 on page 24 illustrates the Pipe function process. Figure 7 Pipe Function Process Outline . PAD Option The PAD option can be used for FXmto with variable-length source datasets and for FXotm with fixed-length target datasets.
DEL Option The DEL option can be used for both FXmto and FXotm operations and enables variable-length records to be transferred between platforms without losing compatibility with the original dataset. When the DEL option is specified for FXmto, FCU adds the specified delimiter to the end of each data entity in the source file, and then extracts and transfers the data entity with delimiter to the open-system target file.
NOTE: If you use FXmto with RDW, the data cannot be transferred back to the original mainframe dataset (the FXotm target dataset will not be compatible with the original dataset). Figure 8 FXmto with the RDW Option . VSE Option The VSE record option must be used for FXmto and FXotm operations involving VSE datasets. The VTOC of a VSE dataset does not specify the RF), RL, or BL of the dataset. The VSE record option enables the user to specify these values so that FCU can process source/target VSE datasets.
transferred to a variable-length or fixed-length target file, depending on the padding option, and delimiters can also be added if desired.
Figure 10 FXmto with Fixed-Length Records: Delimiters . FXmto with Variable-Length Record Format Each variable-length record in a mainframe dataset includes a four-byte RL field and the variable-length data entity. The record length defined for a variable-length dataset equals the maximum allowable record length. NOTE: To transfer the data back to the original mainframe dataset later, you must use FXmto without padding and with delimiters. No padding, no delimiters.
NOTE: If you use FXmto with padding, you will not be able to transfer the data back to the original dataset later using FXotm. Figure 12 FXmto with Variable-Length Records: Padding . With delimiters. Figure 13 on page 29 shows an FXmto operation with delimiters for a variable-length source dataset. The FCU extracts and transfers the data entities to the open-system target file and adds the requested delimiter to the end of each data entity. The RL fields are not transferred.
Figure 14 FXmto with Variable-Length Records: Padding and Delimiters . The resulting length of each data entity in a UNIX target file equals the maximum record length minus 3 bytes (minus 4 for the RL, plus 1 for the delimiter). The resulting length of each data entity in a Windows target file equals the maximum record length minus 2 bytes (minus 4 for the RL, plus 2 for the delimiter).
NOTE: Data Exchange supports two kinds of mainframes: MVS and VSE. For Multiple Volume Dataset, Data Exchange is only supported on MVS. Table 4 Multiple Volume Dataset/Serial Numbers VTOC DSCB1 Dataset Serial Number 1 1 Except 1 Except 1 Last Volume Containing Data in this Dataset, in Dataset Indicators Action On Off On Off OTM Yes(Yes) No(Yes) No(Yes) No(Yes) MTO for single volume1 Yes(Yes) No(Yes) No(Yes) No(Yes) 1 The dataset does not exist in the multiple volume definition file.
NOTE: Do not update the volume that is transferred directly by the FXotm.
Figure 16 FXotm with Fixed-Length Records: Padding . NOTE: The FCU does not extract padding from FXotm source files. With delimiters. Figure 17 on page 33 shows an FXotm operation for a fixed-length source file with delimiters from a previous FXmto transfer. The FCU extracts the data entities from the source file by record length and transfers them to the target dataset. The delimiters are not transferred.
Figure 18 FXotm with Fixed-Length Records: Padding and Delimiters . NOTE: The FCU does not extract padding from FXotm source files. If the FXotm source file contains delimiters, but you specify No for the delimiter option, the delimiters will be regarded as part of the data entities and will be transferred to the target dataset.
Figure 20 FXotm with Variable-Length Records: Padding and Delimiters . If the length of any data entity in a UNIX source file is greater than the specified record length plus 1 byte (CR or LF delimiter), the FCU aborts the operation and reports an error. If the length of any data entity in a Windows source file is greater than the specified record length plus 2 bytes (CR+LF delimiter), the FCU aborts the operation and reports an error.
a file between open-system platforms via a VSE dataset on an -A Data Exchange volume. In this case, you must use the VSE record option for both transfers (FXotm/mto). Host Access and I/O Contention The user must manage access to the FXmto and FXotm volumes to prevent illegal I/O access contention between the mainframe and open-system hosts.
• Reserved by mainframe host. When a Data Exchange volume is reserved by the mainframe host, Data Exchange operations cannot be performed on that volume because the Data Exchange access from the open-system host will terminate unsuccessfully. Open-system access other than read or write I/Os can be executed successfully. NOTE: Open-system access to a mainframe-reserved volume may complete successfully if the open-system retries the operation after the reserve is released.
AIX Shared Open Function To share Data Exchange volumes on multiple AIX operating systems: • For Data Exchange versions 01-xx-59 and earlier, when one AIX OS opens a Data Exchange volume, the other AIX OS cannot open the Data Exchange volume. This is because the AIX OS reserves the Data Exchange volume when it opens it. • For Data Exchange 01-xx-60 and later, it is possible to share a Data Exchange volume across multiple AIX operating systems by specifying the environment variable FAL_NO_RESERVE.
Contact HP technical support for OS/OS versions not listed in Table 8 on page 39. Table 8 OS Version Support for the Retry Reserved-Volume Function OS OS Version Data Exchange Version AIX 4.3.3 ML02 (32/64), 5.1 ML02 (32/64), 5.2 ML02 (32/64), 6.1 TL01 (32/64)1 Tru64 UNIX V5.1a (32) Solaris 8 (32/64), 9 (32/64), 10 (32/64) 01-XX-62 and later (XX = 03 or 04)2 AS3.0 Update3 (32) (x86) (AMD64/Intel64) AS3.0 Update4 (64) (IA64) AS4.
Environment Variable or Function Description FAL_RETRY_WAIT_TIME Set the interval for Data Exchange to send data during reserved status by specifying the environment variable. FAL_RETRY_TARGET Set the system error codes that trigger a retry by specifying the environment variable. Retry function Retry is executed when an AIX system error triggers retry. Output retry log function Data Exchange outputs a retry log (FAL_Error log) when it executes retry.
FAL_RETRY_WAIT_TIME Interval of Retry Others 1 second FAL_RETRY_TARGET. You can set up to five system error codes to trigger the retry function by specifying the environment variable (FAL_RETRY_TARGET). If you set six or more error codes, Data Exchange ignores entries after the fifth entry. Table 13 on page 41 shows the relationship between the environment variable (FAL_RETRY_TARGET) and system error code.
Mon Nov 8 16:21:23 2004 : root : err=16 open Retry(1) at 12345 : 01-03-58/21 PID=1234 VSN:DSN *1 *2 *3 *4 *5 *6 *7 *8 *9 *1 data *2 user name *3 system error code *4 function (open, close, read, write, seek, or flush) *5 retry counts *6 number of source code line *7 version *8 process ID *9 target dataset Figure 21 Retry Log . Errors Table 14 on page 42 shows about error of this function.
NOTE: This function does not work when Data Exchange sends file from Data Exchange volume to an open server. Table 15 Data Exchange Version Support for the Get Detail Traces Function Software OS Version Data Exchange Version FAL for AIX (32/64-bit) FAL for Tru64 (32/64-bit) FAL for Solaris (32/64-bit) Same OS versions that Data Exchange supports.
Table 17 Disk Space for Getting Traces Content Disk Space of Directory For copying sending files More than sending files space. For copying core files About 15 MB. For copying traces Calculate disk space using the following formula: 100 KB + (number of record sending file × 2 bytes) Table 18 Files to Get in case an Error Occurs Content Directory Trace Current directory of FCU: directory set by the environment variable (FCU_E363_TRACE_LOG). Sending file Same directory as sending file.
(2) Set Mode of Making Copy Files You can make copy files before Data Exchange sends by specifying the environment variable (FCU_E363_TRACE_COPY_FILE). Table 20 on page 45 shows the relationship between the environment variable (FCU_E363_TRACE_COPY_FILE) and copy mode.
(5) Check Information for Sending Files When environment variable (FCU_E363_TRACE_MODE) is not set to ON, you can compare information for files (i-node number, file size, file modified) that Data Exchange sends before and after. If Data Exchange found a difference in the data, error FCU_ERROR(-363) occurs after sending the file. When environment variable (FCU_E363_TRACE_MODE) is set to ON, you can compare information for files (i-node number, file size, file modified) while Data Exchange sends files.
Table 24 on page 47 shows the Linux platform support for the interval function. Table 25 on page 47 lists the interval functions for OtM transfer completion. Table 24 Platform Support for the Interval Function for OtM Transfer Linux Platform OS Data Exchange FAL/FCU Notes 7.2 (32-bit) AS2.1 (32-bit) 32-bit version AS3.0 AS4.0 • 32-bit version supports only x86 CPU architecture (7.2, AS2.1). AS5.1 Red Hat AS2.1 (64bit) 64-bit version (IA64 AS2.1) AS3.0 (64-bit) AS4.
Environment Variable for Interval Time You can specify an interval time after the OtM transfer completes by setting environment variable (FCU_OTM_INTERVAL). Table 26 on page 48 shows the relationship between the environment variable (FCU_OTM_INTERVAL) and interval time. Table 26 Relationship between FCU_OTM_INTERVAL and Interval Time FCU_OTM_INTERVAL Interval time No definition The interval function is not available. OtM transfer completes immediately.
3 Preparing for Data Exchange Operations This chapter describes the system and volume configuration requirements to run and operate Data Exchange. It also provides instructions on how to install Data Exchange.
Storage System Data Exchange (32-bit) Version Data Exchange (64-bit) Version XP12000/XP10000 disk array 01-04-61 and later 01-04-61 and later XP1024/XP128 disk array 01-03-53 and later 01-03-59 and later XP512/XP48 disk array 01-02-46 and later None. • HP StorageWorks Remote Web Console and LUN Manager software. LUN Manager enables the user to configure FC ports and create custom-size LUs.
NOTE: There is no guarantee that Data Exchange will correctly access your data without meeting these requirements. Table 28 Support and OS Conditions OS Version Storage System VSE2.5 and later Data Exchange Version XP24000/XP20000 or XP12000/XP10000 disk array 01–03–59 and later When you use MTO and OTM for the dataset allocated by VSE 2.3, you must specify the RF , RL and BL by using the correct VSE parameters. When you use MTO and OTM for the dataset allocated by VSE 2.
BL>32760 For the following dataset attributes, the data transfer is invalid if user does not specify the VSE parameter value between RL and BL values shown in #1 and #2.
Compiler Requirements The compiler requirements are shown in Table 30 on page 53 for each OS. This information is the result of test and evaluation by HP and is guaranteed for the specified development environment for use with Data Exchange. If the development environment differs from that specified here, your results may differ. Table 30 Platforms and Associated Operating Systems Operating System/Platform Compiler Red Hat Linux 7.2 (Kernel version 2.4.7-10) gcc (Ver. 2.96 20000731 (Red Hat Linux 7.1 2.
Maximum Data Size Table 31 on page 54 describes the maximum data sizes for Data Exchange version 01-02-48 or later. Table 31 Maximum Data Size Emulation Type No LUSE LUSE OPEN-3 About 21 GB About 42.8 GB OPEN-8 About 6.5 GB About 42.8 GB OPEN-9 About 6.5 GB About 42.8 GB OPEN-E About 12.9 GB About 42.8 GB OPEN-L About 32.3 GB About 42.8 GB OPEN-V About 42.8 GB About 42.8 GB Multiple Volume Dataset OS limits: 3390-3X About 2.
NOTE: • 3390-9A: Can be used for both FXmto and FXotm. The same access as for 3390-9 is allowed from mainframe hosts. Read and write are possible from open-system hosts. • 3390-9B: Can be used only for FXmto. The same access as for 3390-9 is allowed from mainframe hosts. Read only is allowed from open-system hosts. • 3390-9C: Can be used only for FXotm. The same access as for 3390-9 is allowed but read only from mainframe hosts. Read and write are possible from open-system hosts.
1. Determine exactly how many FXmto, FXotm, and FXoto volumes you will need for your multiplatform data exchange operations. The -A volumes can be used for FXmto, FXotm, and FXoto. The -B volumes are restricted to FXmto. The -C volumes are restricted to FXotm. The OPEN-x FMT volumes are restricted to FXoto. Make sure that the HP service representative installs the desired number of each type of Data Exchange volume during the storage system installation and configuration.
2. Complete the storage system installation and device configuration as specified in the configuration guide for the open-system platform (for example, the HP StorageWorks XP Disk Array Configuration Guide for HP-UX). • Device recognition and device files. For all open-system platforms, you must verify device recognition and device file creation for all Data Exchange volumes. • File system/volume group.
Table 33 Partition Sizes for Storage Systems LVI Cylinder # for Data Cylinder Extent 3390-3A 0 - 3345 3390-3B 0 - 3339 3390-3C 0 - 3345 3390-9A 0 - 10035 3390-9B 0 - 10017 3390-9C 0 - 10035 3390-LA 0 - 32763 3390-LB 0 - 32760 3390-LC 0 - 32763 OPEN-3 0 - 3335 OPEN-8 0 - 9963 OPEN-9 0 - 10013 OPEN-E 0 - 19756 OPEN-L 0 - 49433 3390-3A 0 - 3345 3390-3B 0 - 3339 3390-3C 0 - 3345 OPEN-3 0 - 3335 OPEN-8 0 - 9963 OPEN-9 0 - 10013 OPEN-E 0 - 19756 OPEN-L 0 - 19012 OPEN-
• Volume labels. A Data Exchange volume with a volume label cannot be shared between open-system platforms that use volume labels. Table 33 on page 58 shows the allowable configurations for sharing Data Exchange volumes between open-system platforms for the storage systems. Table 34 on page 59 shows the allowable configurations for sharing Data Exchange volumes between open-system platforms for the storage systems.
IBM AIX NCR SVR4 YES HP-UX Sequent Dynix YES YES Windows YES True64 Solaris YES NO NCR SVR4 NO Linux YES CHK = sharing allowed only if volume has no label. Installing the Data Exchange Software The Data Exchange software must be installed on the open-system servers attached to the storage system. Data Exchange software installation for UNIX-based platforms is different from Data Exchange installation on Windows hosts.
4. Make sure the following six directories exist on the open-system host. If not, create the directories using the mkdir command (for example, # mkdir /usr/lib/X11/app-defaults). /usr, /usr/lib /usr/bin, /usr/lib/X11 /usr/include, /usr/lib/X11/app-defaults 5. Move to the root directory. 6. For UNIX-based systems, copy the Data Exchange software from the installation CD-ROM as follows: # cpio -iBmuv < CD_device_file_name/d NOTE: Use the full device file name: wildcards will not work. 7.
64-Bit Data Exchange Software To install the 64-bit Data Exchange software on a UNIX-based platform: 1. Log in as root. 2. Set the CD-ROM on which the 64-bit Data Exchange is stored to the drive. 3. Mount it. 4. Check to see if the following directories currently exist. If they do not, create them as follows: a. All Platforms: /usr, /usr/lib b. Solaris: /usr/lib/sparcv9 c. HP-UX: /usr/lib/pa20_64 5. Move to the root directory. 6. Copy 64-bit FAL from the CD-ROM. 7.
Uninstalling the Data Exchange Software on UNIX-Based Platforms If you need to uninstall Data Exchange version 01-01-36 or later: 1. Log in to the system as root. Remove the Data Exchange for 32-bit files using the rm command as follows, or string the commands: # rm /usr/bin/fcu # rm /usr/bin/fcunw # rm /usr/include/dataset.h # rm /usr/lib/libfal.* # rm /usr/lib/libfalmt.a (AIX 01-XX-59/20 and later) # rm /usr/lib/libuoc.
Uninstalling Data Exchange on Windows To uninstall the Data Exchange software on a Windows host, depending on your version of Data Exchange, do one of the following: • To uninstall Data Exchange version 01-01-25 or later, use the Windows Add/Remove Programs utility. • To uninstall Data Exchange version 01-01-24 or earlier, delete the folder that contains the Data Exchange software components (fcu.exe, fal.obj, and dataset.h).
• Solaris: 32-bit: ppkeyset /usr/bin/fcunw /usr/bin/fcu /usr/lib/libfal.so.1 64-bit: ppkeyset64 /usr/bin/fcunw64 /usr/lib/sparcv9//libfal64.so.1 • AIX: 32-bit (Version 01-XX-58 and earlier): ppkeyset /usr/bin/fcunw /usr/ bin/fcu /usr/lib/libfal.a For 32-bit (Version 01-XX-59 and later): ppkeyset /usr/bin/fcunw / usr/bin/fcu /usr/lib/libfal.a /usr/lib/libfalmt.a 64-bit: ppkeyset64 /usr/bin/fcunw64 /usr/lib/libfal64.
NOTE: This command does not set the License key to falmt.dll. Use the ppkeyset command to set it. Example: # autoppkeyset /temp/12345.plk PPID=xxx ppkeyset 12345678901234567890 /usr/bin/fcu [/usr/bin/fcu] set in available for all days. --------------------PPID=xxx ppkeyset 12345678901234567890 /usr/bin/fcunw [/usr/bin/fcu] set in available for all days. --------------------PPID=xxx ppkeyset 12345678901234567890 /usr/lib/libfal.xx [/usr/bin/fcu] set in available for all days.
The Data Exchange FMT utility defines the size of the OPEN-x volume in cylinders. The maximum number of cylinders allowed by FMT is shown in Table 35 on page 67.
Block Length by Allocater = (A) (Bytes) Write Available Data per Track (Bytes) Block Length by Allocater = (A) (Bytes) Write Available Data Per Track (Bytes) Block Length by Allocater = (A) (Bytes) Write Available Data Per Track (Bytes) 7477 - 9076 (A) × 5 1269 - 1332 (A) × 26 437 - 468 (A) × 48 6357 - 7476 (A) × 6 1205 - 1268 (A) × 27 405 - 436 (A) × 49 5493 - 6356 (A) × 7 1141 - 1204 (A) × 28 373 - 404 (A) × 50 4821 - 5492 (A) × 8 1077 - 1140 (A) × 29 341 - 372 (A) × 51 4277
2. Enter the following command at the UNIX command line prompt: # mfformat -d devname -v VOLSER [-p primary_cylinders] -d devname: Specify the raw device name (for example, /dev/rdsk/c0t1d2 for HP-UX) of the OPEN-x volume being formatted. This parameter is required. Make sure to use the same raw device name for this volume in the FXoto volume definition file. -v VOLSER: Specify the VSN of the volume being formatted (A-Z, 0-9, @, #, \).
7. When the format operation completes successfully, the Format complete message is displayed (see Figure 25 on page 71). If the specified volser has already been used, an error message is displayed to notify you (see Figure 26 on page 71). If the format operation could not be started due to an error condition, the Format check error message is displayed.
Figure 24 FMT Format Warning and Confirmation . Figure 25 FMT Format Complete Message . Figure 26 FMT VOLSER Used Message . Figure 27 FMT Error Message . Creating the Data Exchange Volume Definition Files The Data Exchange volume definition file contains the volume association parameters for the Data Exchange volumes on the storage systems. This file must be created before you can use FCU or FAL to access data on these volumes.
NOTE: Regarding the specification of the same VSN in volume definition file for 01-XX-48 or later: The same VSN can be defined in the volume definition file using VSN identification, and both volumes can be used by FXotm and FXmto. The definitions should be defined with 35 digits, using the alphabetic (A-Z, @, #, and \) or numeric (0-9) characters. The -A, -B, and -C Data Exchange volumes and the OPEN-x-FXoto volumes can be defined in the same Data Exchange volume definition file.
2. Add the volume association parameters for the Data Exchange volumes to the file. • Put at least one space between each parameter, and press Return at the end of each line to separate the parameter sets. All three parameters (device name, volser, LVI type) are casesensitive. If you add comments to the file, make sure that each comment line starts with #. Make sure to enter end on the last line of the file. 3.
/dev/rrzX1Y1Z1 /dev/rrzX3Y3Z3 /dev/rrzX4Y4Z4 (1) end (5) AAAAAA cccccc dddddd (2) 3390-3A 3380-KB 3380-KA (3) MFN MFN (4) MVS VOS3 (5) (6) Figure 31 Data Exchange Volume Definition File for DIGITAL Tru64 UNIX (oto Shown) . NOTE: X = b through h = LUN1 through LUN7 (no letter is used for LUN0); Y = fibre bus number × 8 + SCSI TID; Z = partition = a through h. For example, rrzc18a = SCSI TID 2, LUN2 (partition a) on fibre bus 2. \\.\PHYSICALDRIVE0 AAAAAA \\.\PHYSICALDRIVE1 AAAAAA \\.
/dev/rsda /dev/asdb /dev/rsd /dev/rsd (1) end (7) AAAAAA AAAAAA ccccccc ddddddd (2) 3390-3A 3390-3A 3380-KB 3380-KA (3) (4) MFN MFN MVS1 VOS3 (5) (6) Figure 35 Data Exchange Volume Definition File for Linux . Verifying Mainframe Dataset Requirements FAL and FCU have specific requirements for the Data Exchange source and target datasets. Table 38 on page 75 specifies the requirements for Data Exchange datasets.
Item Requirements Any length within the extent supported by the OS. If an illegal RL is detected, Data Exchange will return an error. NOTE: Record length (RL) Data Exchange cannot process a variable-length dataset that includes a record with no data entity (RL = 4). For FXotm, the record length of the target dataset must be preconfigured to match the record length of the data entities in the source file. For VSE source and target datasets, the FCU VSE record option must be used to specify the RL.
UNIX To allocate an FXoto intermediate dataset using the ALC utility: 1. Log in to the system as root. 2. Enter the following command at the UNIX command line prompt: # allocds -d devname [-n datasetname] [-f recform] [-r reclen] [-b blocklen] [-c cylinders] NOTE: Enter only one value for each parameter. You can only allocate one dataset at a time. -d devname: Specify the raw device name of the OPEN-x volume on which the dataset is being allocated. This parameter is required and must be specified.
3. The ALC utility automatically displays the first OPEN-x FMT volume (in alphanumeric order) in the VOLSER field. If this is not the desired volume, select the desired volume from the list of volsers. If ALC could not find any OPEN-x FMT volumes, ALC displays the Data Exchange format disk not found message. 4. Enter the name of the dataset being allocated in the Dataset field (maximum 44 characters: A-Z, 0-9, @, #, ., \). Do not use any spaces or symbols other than @, #, ., and \. 5.
Figure 36 ALC Utility for Windows Systems . Figure 37 ALC Disk Not Found Message . Figure 38 ALC Allocation Complete Message .
Figure 39 ALC Error Message .
4 Using the Data Exchange Software This chapter describes the user interface and the commands available to a Data Exchange user. • • • • FCU for UNIX, page 81 FCU for Windows, page 86 Format Utility for Windows, page 95 ALC Utility for Windows, page 100 FCU for UNIX The FCU GUI enables you to perform Data Exchange file transfer operations interactively and provides access to detailed information on the datasets/files in the specified Data Exchange source volume/directory.
1. At the UNIX command line prompt, enter: fcu [-nc] [param] The -nc option (nc = no checking) tells FCU to execute all specified Data Exchange operations without requesting confirmation for FCU parameters or checking for existing FXmto target files. To bypass these confirmations, enter -nc. The param option tells FCU whether to use the FCU parameter definition file or a specific FCU initiation parameter set to perform Data Exchange operations.
File Conversion Utility Screen The FCU main panel opens when the FCU GUI program is finished loading. The FCU main panel displays the FCU initiation parameter sets in the specified FCU parameter definition file (if available), allows you to perform Data Exchange operations, and provides access to all FCU functions. Figure 41 FCU Main Panel for UNIX Platforms . The File and Help buttons display the File menu commands and Help menu commands. These commands are described later in this section.
• Direction. The Direction buttons allow you to select the desired direction for the Data Exchange operation: M to O = FXmto, O to M = FXotm. • Input File. The Input File field allows you to enter the name of the Data Exchange source file. For FXmto, enter the mainframe volser and dataset name (VSN:dataset). For FXotm, enter the UNIX file name (with complete path if not in the current directory). • Output File. The Output File field allows you to enter the name of the Data Exchange target file.
parameter set. If you make changes and do not click Save, the FCU will discard your changes when you select Load or Exit. • Delete. This command deletes the currently loaded parameter set from the FCU parameter definition file. If the FCU parameter definition file does not yet exist or does not contain the parameter set on screen, the FCU ignores this command. • Exit. This command closes the current FCU parameter definition file (unsaved changes are discarded), and then closes the FCU program.
Dataset Information : VSN = xxxxxx Dataset Name *SAMFILE01.FIX -DAMFILE.F *SAMFILE02.VAR -PAMFILE -VIRTUALSTORAGEACCESS -UNDEFSAMFILE -SAMFILESPANNED Device Emulation Type = 3390-3B DO RF BL RL DS SAM DAM SAM PAM VSAM SAM SAM F F V F V U S 4096 4096 4000 5000 32768 8000 8192 128 128 80 100 4096 200 8192 150 30 50 200 3000 80 300 Can be processed by FCU. Cannot be processed by FCU. Can be processed by FCU. Cannot be processed by FCU. Cannot be processed by FCU. Cannot be processed by FCU.
2. Start the FCU GUI as follows: Click Start-Programs-FCU-FCU, or open the c:\ folder and double-click FCU, or create a shortcut for FCU on the desktop. NOTE: Do not start the FCU by dragging and dropping an FCU parameter definition file on the FCU program icon. FCU program operation cannot be guaranteed. 3. To specify any of the FCU options, start the FCU from the command line (DOS prompt) as follows: Go to the FCU directory (containing fcu.exe and datasetmount.
Figure 47 FCU Main Panel for Windows Systems . The FCU title bar displays the current FCU parameter definition file. The toolbar provides speed buttons for the commonly used FCU functions. The status bar displays the current line number and total number of lines in the current FCU parameter definition file. The Main frame file and Open-system file fields display the files to be transferred (no spaces allowed). The file selection buttons ( select the desired mainframe dataset and Windows file.
• The Parameter-Load command loads the Previous, Next, Top, and Bottom parameter lines from the current FCU parameter definition file. The FCU main panel status bar updates the current line number when any Parameter-Load command is executed. • The Parameter-Save command allows you to either Insert the parameter set being displayed into the current FCU parameter definition file, or Replace the current parameter set (previously loaded) with the parameter set being displayed.
Figure 48 Volume Information Panel . NOTE: This example shows a Data Exchange volume definition file that defines only one Data Exchange volume. Mainframe File Information Dialog The View-MF-file information… command displays the following information for the mainframe (MF) files (datasets) in the volume specified in the Mainframe file field on the FCU main panel: • = the dataset can be processed by FCU. = the dataset cannot be processed by FCU.
Figure 49 MF-File Information Panel . NOTE: This example shows a Data Exchange volume (3380-KA, VSN = AAAAAA ) that contains only two datasets. NOTE: When this panel is opened using the Mainframe file selection button ( displayed. ), only SAM datasets are Option Dialog The View-Option… command opens the Option panel, which allows you to view/change the FCU file transfer options (code conversion, padding, delimiter, empty file, RDW, and VSE), continuous execution option, and clear log file option.
Figure 50 Option Panel . • Select the EBCDIC<-->ASCII option to use the default code conversion table (EA, EcA). Select No for no code conversion (No). Select External table file and enter the file name with the path if not in the current directory (for example, /directory/filename.tbl). • • • • Select the Padding box to request the padding option (Yes). Select the Delimiter box to request the delimiter option (Yes). Select the Empty box to request the empty file option (Emp=Yes).
• The Parameter-Load command loads the Previous, Next, Top, and Bottom parameter lines from the current FCU parameter definition file. The FCU main panel status bar updates the current line number when any Parameter-Load command is executed. • The Parameter-Save command allows you to either Insert the parameter set being displayed into the current FCU parameter definition file, or Replace the current parameter set (previously loaded) with the parameter set being displayed.
Figure 52 Execute Panel Showing Normal End . When the operation is complete, the Execute panel displays the result. If an error occurred, the Error information panel opens automatically to display the error. See “Error Codes and Messages” on page 150 for further information on errors. To cancel the operation in progress, click Cancel. Figure 53 Execute Panel Showing Canceled Operation . If an error occurred, the Error information panel opens automatically to display the error).
Figure 55 Error Information Panel . Log Files The View-Log file command opens the log file for the current FCU parameter definition file using the Windows Notepad text editor. The log file contains the parameter sets executed, the date and time of execution, the result of each operation, and the error information (FCU, FAL, and Sys error codes) for each operation. Figure 56 FCU Log File Display in Notepad .
NOTE: FCU version 01-01-42 or later is required for the FMT utility. The FMT utility defines the size of the OPEN-x volume in cylinders. The maximum number of cylinders allowed by FMT is shown in Table 39 on page 96.
Block Length by Allocater = (A) (Bytes) Write Available Data per Track (Bytes) Block Length by Allocater = (A) (Bytes) Write Available Data Per Track (Bytes) Block Length by Allocater = (A) (Bytes) Write Available Data Per Track (Bytes) 15477 - 23476 (A) × 2 1493 - 1588 (A) × 23 533 - 564 (A) × 45 11477 - 15476 (A) × 3 1397 - 1492 (A) × 24 501 - 532 (A) × 46 9077 - 11476 (A) × 4 1333 - 1396 (A) × 25 469 - 500 (A) × 47 7477 - 9076 (A) × 5 1269 - 1332 (A) × 26 437 - 468 (A) × 48
1. Log in to the system as administrator. 2. Double-click the Format icon to open the Format panel (see Figure 57 on page 98). Figure 57 FMT Utility for Windows Systems . 3. On the Format panel, enter the 6-character volume serial number for the OPEN-x volume being formatted in the VOLSER field. Make sure to use the same volser for this volume in the FXoto volume definition file. 4.
7. When the format operation completes successfully, the Format complete message is displayed (see Figure 59 on page 99). Figure 59 FMT Format Complete Message . If the specified volser has already been used, an error message is displayed to notify you (see Figure 60 on page 99). Figure 60 FMT VOLSER Used Message . If the format operation could not be started due to an error condition, the Format check error message is displayed. Figure 61 FMT Error Message .
IMPORTANT: When the message Format check error is indicated, the formatting operation has not started and the original condition has been kept. When another message is indicated, the formatting process has already started. The data on the volume has already been initialized. Remove the error condition and format the volume again. If you execute over the maximum number of cylinders on Windows 2003, the message Format failed … Format check error appears after about 1 minute.
5. Enter or select the size of the new dataset (number of cylinders, number of tracks) in the Cylinder and Track fields. The file size will be (# of cyl) + (# of tracks). The Max. button enters the maximum size for the new dataset in the Cylinder and Track fields based on the available capacity. The Available Capacity box displays the free space on the specified volume, so that you can select the appropriate size for the new dataset. 6.
Figure 62 ALC Utility for Windows Systems . Figure 63 ALC Disk Not Found Message . Figure 64 ALC Allocation Complete Message .
Figure 65 ALC Error Message .
Using the Data Exchange Software
5 Performing Data Exchange Operations This chapter describes how to operate Data Exchange. • Performing File Transfer Operations—UNIX, page 105 • Performing File Transfer Operations—Windows, page 115 Data Exchange file transfer operations are performed using the FCU GUI software installed on the open-system hosts attached to the storage system.
Starting the FCU GUI for UNIX To start the FCU GUI program for UNIX-based platforms: 1. At the UNIX command line prompt, enter: fcu [-nc] [param] The -nc option (nc = no checking) tells FCU to execute all specified Data Exchange operations without requesting confirmation for FCU parameters or checking for existing FXmto target files. To bypass these confirmations, enter -nc.
3. If you specified the -nc option, FCU processes all specified operations, overwrites existing mto target files, terminates, and displays any error information at the UNIX prompt. Figure 66 FCU Version and Copyright Screen (UNIX) . Performing File Transfer Operations (UNIX) To perform file transfer operations using the FCU GUI for UNIX: 1. 2. 3. 4. If you will be performing FXmto operations: a. Make sure that the source datasets are located on the desired Data Exchange volumes.
5. Start FCU with the desired options (see “Starting the FCU GUI for UNIX” on page 106). NOTE: If you specify the -nc option, FCU performs all specified operations continuously, then self-terminates and displays any error information at the UNIX prompt. 6. When the FCU main panel opens, make sure that the Volume File field displays the Data Exchange volume definition file (datasetmount.dat).
Using the listvol Function (UNIX) The listvol VSN function enables FCU users to access the mainframe dataset information without having to launch the FCU GUI (and use the Help-MF-File command). The listvol VSN UNIX command displays the dataset information for the specified VSN. The listvol VSN function requires the Data Exchange volume definition file. NOTE: The listvol VSN function is available in FCU for UNIX versions 01-01-41 and later. Specify 6-character VSN.
3. If you plan to perform Data Exchange operations while you are creating the FCU parameter definition file, make sure that the Volume File field displays the correct Data Exchange volume definition file (datasetmount.dat). If not (or if incorrect), FCU will not be able to perform Data Exchange operations, but you can still create a new FCU parameter definition file. 4. Select the File-Load command to open the new file. 5.
VSN:DSN[,VOLID1] VSN[,VOLID2] i) ii) iii) end v) ----iv) VSN[,VOLIDn] Figure 68 VSN Function . 1. This parameter is the information for the head volume. • VSN: A volume serial number with six alphabetic (A-Z, @, #, and \) or numeric (0-9) characters. • DSN: Dataset name. (Use a maximum of 44 alphabetic or numeric characters.) • VOLID1: A VSN identification.
• The -nw option (nw = no Windows) tells FCU to execute the specified Data Exchange operations without displaying the GUI. When you use this option (entered as fcunw or fcu -nw), FCU uses the FCU initiation parameters specified by the param option to perform Data Exchange operations. To use FCU without the GUI, the -nw option is required. NOTE: FCU versions 01-01-36 and later for Windows systems do not support the -nw option.
2.
# fcunw File Conversion Utility Ver.01-01-40/00 Start FCU with checking. FCU program version. mto VSN:dataset file_name EA No LF ok/cancel ? ok Now checking... Complete First set of parameters. Enter ok or cancel. Checking for target file. Operation completed. otm file_name VSN:dataset EA No No ok/cancel ? ok Input file : Open error (-350) (Fal error : xxx (System error : xxx Next set of parameters. Enter ok or cancel. Error info displayed.
Performing File Transfer Operations—Windows Starting the FCU GUI To start the FCU GUI program for Windows systems: 1. Log on with Administrator access privileges. 2. Start the FCU GUI as follows: Click Start-Programs-FCU-FCU, or open the c:\ folder and double-click FCU, or create a shortcut for FCU on the desktop. NOTE: Do not start FCU by dragging and dropping an FCU parameter definition file on the FCU program icon. FCU program operation cannot be guaranteed. 3.
Figure 72 FCU Version and Copyright Screen (Windows Systems) . Performing File Transfer Operations (Windows) To perform Data Exchange file transfer operations using the FCU GUI for Windows systems: 1. 2. 3. 4. 116 If you will be performing FXmto operations: a. Make sure that the source datasets are located on the desired Data Exchange volumes.
5. Start FCU (see “Starting the FCU GUI” on page 115). To specify any FCU options, start FCU from the DOS prompt. NOTE: If you specify the -nc option, FCU performs all specified operations continuously, then self-terminates and displays any error information at the DOS prompt. 6. When the FCU main panel opens, select the View-Volume information… command ( ) to open the Volume information panel, and verify that the desired Data Exchange volumes are available.
11. When FCU starts the operation, the Execute panel opens and displays the progress of the operation. To cancel the operation in progress, click Cancel. NOTE: The Execute panel will not appear when the mainframe OS is VSE. 12. When the operation is complete, the Execute panel displays the result. If an error occurred, the Error information panel opens automatically to display the error. See “Error Codes and Messages” on page 150 for further information on errors. 13.
Figure 74 Execute Panel Showing Canceled Operation . Figure 75 Execute Panel Showing Error End . Creating FCU Parameter Definition Files (Windows) To create an FCU parameter definition file using the FCU GUI for Windows systems: 1. Start the FCU GUI for Windows systems (see “Starting the FCU GUI” on page 115). If you start FCU from the DOS prompt, enter fcu (do not specify the -nc or param option). 2.
6. Repeat steps (4) and (5) to add each new FCU initiation parameter set to the new FCU parameter definition file. If desired, you can use the Parameter-Wipe menu command ( ) to clear the screen before you enter the next set of parameters, or you can leave the parameters and make changes where needed to specify the next new line in the file. Make sure to keep Data Exchange operations that use OPEN-x FMT volumes in a separate FCU parameter definition file from operations that use -A, -B, and -C volumes. 7.
• VSN: A volume serial number with six alphabetic (A-Z, @, #, and \) or numeric (0-9) characters. • VOLID2: A VSN identification. (Omit this parameter if a VSN identification is omitted in the volume definition file, and specify the same as the volume definition file if a VSN identification is specified in the volume definition file.) 3. This parameter is the information for the last volume.
2. Open the command prompt (DOS Windows) and input the parameters below: • fcunw [-cl] [param] ( [-v] ) • -cl: Specifies that all the log files for FCU will be cleared before stating FCU. • param: This parameter is used the as same as (1) in this section for UNIX. NOTE: When this parameter is not specified, the file name of the parameter definition file will be assumed to be fcudata.prm and it will attempt to read the detail parameters from the file. • -v: This displays the version of fcunw.
6 Performing FAL Operations This chapter describes how to perform FAL operations using Data Exchange. • • • • • • • FAL Requirements, page 123 FAL Functions, page 124 Using the FAL Functions, page 132 Multi-Thread Function, page 136 Compiling, page 145 Error Information, page 146 FAL Usage Scenario, page 146 The FAL component of Data Exchange consists of the object module file fal.o (fal.obj for Windows systems) and the header file dataset.h.
FAL Functions The FAL includes the following C functions (Visual C++ for Windows systems): • Opening a dataset: datasetOpen (see “Opening a Dataset” on page 124) • Reading one record from a dataset: datasetGet (see “Reading Data” on page 125) • Writing one record to a dataset: datasetPut (see “Writing Data” on page 126) • Closing a dataset: datasetClose (see “Closing a Dataset” on page 127) • Acquiring error information: datasetGetLastError (see “Acquiring Error Information” on page 127) • Acquiring dataset
When the datasetOpen function terminates successfully, it returns a handle that identifies the dataset opened. The datasetHandle information is used as the argument of subsequent functions such as datasetGet, datasetPut, or datasetClose. Do not change the datasetHandle value returned by this function. If the datasetOpen function terminates unsuccessfully, it returns a value of -1. To get the error code information, execute the datasetGetLastError function (see “Acquiring Error Information” on page 127).
Figure 77 Format Requirements for Reading Variable-Length Records . When the datasetGet function terminates successfully, it returns the length of the data entity read from the dataset. If the datasetGet function detects the end of dataset (EOF) or terminates unsuccessfully, it returns a value of -1. To get the error code information, execute the datasetGetLastError function (see “Acquiring Error Information” on page 127).
dataset. When the data is written into the dataset, multiple records are blocked within the extent defined by the VTOC of the dataset. Figure 78 Format Requirements for Writing Variable-Length Records . When the datasetPut function terminates successfully, it returns the length of the data entity written to the dataset. If the datasetPut function terminates unsuccessfully, it returns a value of -1.
attached with Microsoft Visual C++. Table 45 on page 128 shows the datasetClose arguments and return values. Table 45 DatasetGetLastError Function Item Value Type Description Argument none — — Return value datasetLastError Long Error code Acquiring Dataset Attributes FAL provides several functions for acquiring the complete dataset attribute information for one or more datasets: datasetGetFileInformation, datasetFindFirstFile, datasetFindNextFile, and datasetFindClose.
When the DatasetGetFileInformation function terminates successfully, it returns a value of 0. If it terminates unsuccessfully, it returns a value of -1. To get the error code information, execute the datasetGetLastError function (see “Acquiring Error Information” on page 127). The DatasetGetFileInformation function has the following restriction: • The DatasetGetFileInformation function cannot be used on an open dataset. Use this function before opening or after closing the dataset.
2. datasetError = datasetFindNextFile (datasetHandle, &ffd) The datasetFindNextFile function acquires the attribute information for the next dataset in the volume specified by datasetHandle and returns the data into ffd. This function can be repeated until “no dataset found” is returned or until the user application determines that no more information is needed. Table 48 on page 130 shows the datasetFindNextFile arguments and return values.
Converting DO and RF Information The FAL provides two functions for converting specific attribute information from a dataset into character strings: datasetGetDsorgString and datasetGetRecfmString. Converting the Dataset Organization (DO) Type Value datasetError = datasetGetDsorgString (dsorg, text) The datasetGetDsorgString function converts the dataset organization (DO) type to a 3-byte character string. The DO type is specified by dsorg[2] in DATASET_FIND_DATA.
The datasetGetRecfmString function converts the RF type to a 5-byte character string. The RF type is specified by recfm in DATASET_FIND_DATA. Table 51 on page 132 lists the datasetGetRecfmString arguments and return values. Table 51 DatasetGetRecfmString Function Item Value Type Description Record type value (1 byte) recfm u_char Sets value of recfm, a member of DATASET_FIND_DATA, which is obtained by datasetGetFileInformation/ datasetFindFirstFile/ datasetFindNextFile, to recfm.
3. Using 32-bit FAL, compile the C program as follows: • IBM AIX # cc -qlanglvl=ansi —D_NO_MT -o Output file name Source file name /usr/lib/libfal.a libfal.a = file name of FAL object module • HP-UX # cc -Ae +DAportable —D_NO_MT -o Output file name Source file name /usr/lib/libfal.sl libfal.sl = file name of FAL object module • Solaris # cc —D_NO_MT -o Output file name Source file name /usr/lib/libfal.so.1 libfal.so.
4. Using 64-bit FAL, compile the C program as follows: • IBM AIX # cc -qlanglvl=ansi -q64 —D_NO_MT -o Output file name Source file name /usr/lib/libfal64.a libfal64.a = file name of FAL object module • HP-UX # cc -Ae +DAZ.0W —D_NO_MT -o Output file name Source file name /usr/ lib/pa20_64/libfal64.sl libfal64.sl = file name of FAL object module. • Solaris # cc xarch=v9 —D_NO_MT -o Output file name Source file name /usr/ lib/sparcv9/libfal64.so.1 libfal64.so.1 = file name of FAL object module.
Figure 79 Example of Reading Data from a Mainframe Dataset Using FAL .
Figure 80 Example of Acquiring MF Dataset Attributes Using FAL .
• Get a dataset attribute: dataset_GetFileInformation, dataset_FindFirstFile, dataset_FindNextFile, dataset_FindClose Programming Restrictions: • You cannot use Data Exchange from the Signal Handler. • The following words are reserved words.
• When this function ends abnormally, it returns a 0. For further information, see Chapter 7 on page 149.
void *memptr; /* global memory area */ long err,datasetError; /* global err information */ int retcode; retcode = dataset_AllocGlobal(&memptr, &err, malloc, free); : datasetError = dataset_Open(memptr, &err,” HYPERLINK “\\\\.\\PHYSICALDRIVE1” \\.
• When this function ends normally, reclen (record length) is returned. (0 record length 32760). • When this function ends abnormally, “- 1” is returned. • When this function detects EOF, “DATASET_ERROR_END_OF_FILE” is returned. NOTE: When “- 1” is returned, see the content of g_error for error code details. For further information, see Chapter 7 on page 149.
Close Dataset • Format: datasetError=dataset_Close(global,g_error) Table 56 Arguments, Types, and Descriptions for Close Dataset Argument Type Description global void Global memory area g_error long An error information stored area datasetError Return value: long -1 Abnormal end This function closes a dataset. • Return value: • When this function ends normally, “0” is returned. • When “- 1” is returned, see the content of g_error for error code detail.
Initialize Target Record Pointer • Format: datasetError=dataset_Rewind(global,g_error) Table 58 Arguments, Types, and Descriptions for Initialize Target Record Pointer Argument Type Description global void Global memory area g_error long1 An error information stored area datasetError Return value: long -1 Abnormal end 1 When this function is issued before dataset_Put, dataset_Put2, dataset_Get, and dataset_Get2, the pointer is returned to the top record.
• global: Global memory area (specify a global memory area gotten by dataset_AllocGlobal). • g_error: Specify an address to store the FAL error code. • ffd: A first dataset attribute information stored area.
• global: Global memory area (specify a global memory area gotten by dataset_AllocGlobal). • g_error: Specify an address to store the FAL error code. • Pathname: Address of the partition name/physical drive name. • Voltype: Device emulation type (3390-3A/9A/LA, 3390-3B/9B/LB, 3380-3A, and 3380-3B). • ffd: A first dataset attribute information stored area. • Return Value (1): • When this function ends normally, “DATASET_HANDLE” is returned.
• When this function ends normally, “0” is returned. • When this function ends abnormally, “- 1” is returned. • When “- 1” is returned, see the contents of g_error and for error code details. For further information, see Chapter 7 on page 149. • When there is no dataset in the VTOC, the return value is “- 1” and the error information is DATASET_ERROR_END_OF_VTOC. NOTE: You must issue dataset_FindFirstFile before this function.
3. Copy the following FAL files to the project folder/directory: • dataset.h • falmt.dll • falmt.lib 4. Select SETTING on the Developer Studio PROJECT menu. 5. Select the LINK tab in the Project setting dialog. 6. Add falmt.lib to the OBJECT/LIBRARY MODULE column. 7. Build/Execute. NOTE: For AIX systems: #cc −qlanglvl=ansi −o output file name source file name /usr/lib/libfalmt.a • libfalmt.a: object module file name of Multi-thread for FAL.
Figure 81 Example of Using FAL to Read Data .
Performing FAL Operations
7 Troubleshooting This chapter provides descriptions of error codes and support desk contact data. • Troubleshooting, page 149 • Error Codes and Messages, page 150 • Calling HP Technical Support, page 169 Troubleshooting For general troubleshooting information, see the HP StorageWorks Disk Array Owner’s Guide for the storage system. When errors are detected, error codes and messages are displayed and/or logged.
Error Condition Recommended Action FCU reports code conversion table errors. If you specified your own code conversion table, make sure that the file name and path are correct. FCU may also report code conversion table errors when the Data Exchange volume definition file contains both mainframe and OPEN-x Data Exchange volumes. Keep the FXoto volume definition file separate from the FXmto/otm volume definition file.
Error Code Error Message and Description DATASET_ERROR_RECFM_NOT_SUPPORTED -12 The record format is not supported. DATASET_ERROR_INVALID_DATA -13* The data in the VTOC or the dataset is invalid. DATASET_ERROR_VOLUME_DEFINITION_INVALID -14* The format of volume definition file is invalid. DATASET_ERROR_DATASET_NOT_OPENED -15 An attempt was made to read the dataset without opening it.
Error Code Error Message and Description DATASET_ERROR_INVALID_ARGUMENT -21 An argument of the function is invalid. DATASET_ERROR_NO_DATASET -22 No dataset was found. DATASET_ERROR_NON_STANDARD_R0_EXIST -23* Nonstandard record 0 (R0) exists. DATASET_ERROR_INVALID_MODE -24 The mode argument of datasetOpen is not valid. DATASET_ERROR_VOLUME_DEFINED_READ_ONLY -25* The open-system host tried to write to a read-only volume. FAL_INTERNAL_ERROR -26 Internal error of FAL.
Error Code Error Message and Description DATASET_ERROR_MULTI_VOLUME_DEFINITION_RECORD_OVER -39 The number of parameter sets for a multiple volume definition file exceeded 1,000. DATASET_ERROR_MULTI_VOLUME_NO_DATASET -40 -41 The dataset does not exist in the next volume. DATASET_ERROR_MULTI_VOLUME_NO_TRANSFER DATASET_ERROR_MULTI_VOLUME_DEFINITION_INVALID_RECORD_LENGTH -42 The record length in the multiple volume definition file is too long.
FCU Error Codes for UNIX If the FCU for UNIX reports an error, use the Help-Error command to view the most recent error. Table 66 on page 154 lists and describes the FCU error codes for UNIX and provides instructions for resolving each error condition. In Table 66 on page 154, the error codes marked by an asterisk (*) may also be reported when I/O access contention for the Data Exchange volume occurs between the mainframe and open-system hosts.
Error Code Error Message and Description Recommended Actions Parameter file: PADDING error -108 The padding option specified in the parameter definition file is not valid. Make sure that the padding is specified as either Yes or No. Parameter file: DELIMITER error -109 The delimiter option specified in the parameter definition file is not valid. Parameter file: Open error -110* An error occurred when opening and outputting the parameter definition file.
Error Code Error Message and Description Overwrite ? (OK/Cancel) -120 This message asks you to confirm whether to overwrite the existing file. Output file: File name error -121 The output file name is not specified. Output file: Open error -122* An OPEN error occurred when checking to see if the output file exists. Recommended Actions The specified open-system target file already exists. Click OK to overwrite the file, or click Cancel to specify a different target file.
Error Code Error Message and Description Parameter error: No input file name -135 The input VSN is not specified. Recommended Actions Specify the VSN of the mainframe source dataset before selecting the Help-MF-File command. Parameter error: VSN error -136 The input VSN is incorrect. Make sure that the VSN has six characters. Dataset error: No dataset -137 The specified volume has no datasets. Dataset error: Search error -138* An error occurred when searching the dataset.
Error Code Error Message and Description Recommended Actions Output file: Get file data error -152 A data acquisition error of the output file occurred during an FXotm operation. Processing data: Length check error -153 A data length to be processed by FXotm does not match. Buffer: Memory allocation error -155 Memory allocation failed. Input file: Read error -160* A read error occurred in the input dataset. Output file: Write error -161* A write error occurred in the output UNIX file.
Error Code Error Message and Description Recommended Actions UNIX file: Not a directory -181 The specified name is not a directory name. UNIX/Open system file: Open directory error -182* A directory open error occurred. UNIX/Open system file: Close directory error -183 A directory close error occurred. Input file name: No data -190 The input file name is not specified. Output file name: No data -191 The output file name is not specified. Check the specified directory name.
Error Code Error Message and Description Recommended Actions RDW error: PADDING not supported -206 Padding is not specified as No when RDW=Yes. Padding cannot be processed when RDW=Yes. Change the padding parameter to No. RDW error: DELIMITER not supported -207 Delimiter is not specified as No when RDW=Yes. Parameter file: Comment line -210 This is a comment line in the parameter file. Parameter: VSE select error -220 The VSE parameter format is not correct.
Error Code Error Message and Description Recommended Actions Code conv. table: File size error -235 The size of the code conversion table is not correct. Make sure that the size of the code conversion table is 256 bytes. Code conv. table function: Invalid argument -236 No source data to be converted was found. Code conv. table name: No data -238 The file name of the code conversion table is not specified.
Error Code Error Message and Description Input file error: Invalid record length -343 The record length of the dataset is invalid. Input file: Open error -350* An open error occurred in the input UNIX file. Output file: Open error -351* A file open error occurred in the output dataset. Recommended Actions Display the attribute information using the HelpMF-File command. The record length must be nonzero and cannot be greater than 32 kB. Display the system error code using the HelpError command.
Error Code Error Message and Description Output file: Close error -371 A file close error occurred in the output dataset. Recommended Actions Display the error code using the Help-Error command. If a FAL error code is displayed, see Table 65 on page 150. If a system error code is displayed, see the OS user manual. UNIX file: No data -379* No data was found in the input UNIX file. Make sure to specify an input file that contains data. No UNIX file -380 The specified UNIX file was not found.
fcudata.prm.log). Table 67 on page 164 lists and describes the FCU error codes for Windows 2000/Windows NT systems and provides instructions for resolving each error condition. NOTE: Error codes with a plus value are system errors. Windows systems system error codes are defined in the errno.h file attached with Microsoft Visual C++.
Error Code Error Message and Description Recommended Actions Parameter: RDW duplication error -110 More than one RDW setting is specified. Volume definition file: Open error -120 An error is detected when opening the volume definition file. Specify only one RDW setting. Make sure that the volume definition file was created correctly. If the volume definition file is correct, check the system error.
Error Code Error Message and Description Recommended Actions Dataset: Record length error -136 The specified record length is not correct. Dataset: Dataset size error -137 The specified dataset size is not correct. Make sure that the record length is specified correctly. Make sure that the dataset size is specified correctly. Dataset: Close error -138 An error is detected during a close operation. Check the FAL error code and system error code.
Error Code Error Message and Description Recommended Actions Open system file: Close error -173 An error is detected when closing the open system file. Open system file: No data error -174 No dataset is found. Check the system error. Make sure that the open-system file has data. If not, create the appropriate data in the opensystem file. Open system file: Delimiter (CR) position error -175 A delimiter (CR) position error is detected.
Error Code Error Message and Description Recommended Actions External table file: Close error -223 The code conversion table could not be closed. Parameter: Direction, PAD, and DEL not matched -240 The combination of otm direction, PAD=Yes, and DEL=No is not allowed. Parameter: Direction and RDW not matched -241 The combination of otm data transfer direction and RDW=Yes is not allowed. Parameter: Code conv.
Error Code Error Message and Description Recommended Actions Opensystem file name : Length error -302 An input filet name (in the case of FXotm) or an output file name (in the case of FXmto) in the parameter definition file is too long. Specify an input/output file name that is less than 1,025 characters. Code conversion Length error -303 A code conversion file name in the parameter definition file is too long. Specify a code conversion file name that is less than 1,025 characters.
• The FAL error logs. The FAL logs for UNIX are /tmp/fal_error and /tmp/fal_error.bak, and /tmp/fal_dump and /tmp/fal_dump.bak. The FAL logs for Windows systems are c:\ fal_error and c:\fal_error.bak, and c:\fal_dump and c:\fal_dump.bak. • Windows systems only: The FCU log file (for example, fcudata.prm.log) and Dr. Watson’s log file (for example, c:\WINNT\DRWTSN32.LOG). • The Syslog: Error information and other applicable contents.
8 Support and Other Resources Related Documentation • • • • • • • HP StorageWorks Data Exchange Code Converter User's Guide HP StorageWorks XP24000/XP20000 LUN Manager User’s Guide HP StorageWorks XP24000/XP20000 LUN Expansion User's Guide HP StorageWorks XP24000/XP20000 Remote Web Console User’s Guide HP StorageWorks XP24000/XP20000 Virtual LVI/LUN (VLL) and Volume Shredder User's Guide HP StorageWorks XP24000/XP20000 Disk Array Owner's Guide Hitachi Dynamic Link Manager Software User's Guide for AIX • •
HP Technical Support For worldwide technical support information, see the HP support website: http://www.hp.com/support Before contacting HP, collect the following information: • • • • • • Product model names and numbers Technical support registration number (if applicable) Product serial numbers Error messages Operating system type and revision level Detailed questions Subscription Service HP recommends that you register your product at the Subscriber's Choice for Business website: http://www.hp.
A EBCDIC-ASCII Code Conversion This appendix provides a list of EBCDIC to ASCII conversion values. Table 68 on page 173 lists the EBCDIC-ASCII code conversions performed by the default code conversion table that is provided with FCU).
Hex EBCDIC ASCII Hex EBCDIC ASCII Hex EBCDIC ASCII Hex EBCDIC ASCII 16 BS GE 36 UC o 56 76 { 17 IL g 37 EOT PF 57 77 A 18 CAN CAN 38 q 58 78 B 19 EM EM 39 r 59 79 ‘ 1A CC k 3A ^ 5A ! SOS 7A : 1B CUI 5B $ BYP 7B # 1C IFS 5C * SW 7C @ SP 1D 5D ) 7D ‘ ESC 5E : CU3 7E = NAK FS 3B CU3 IFS 3C DC4 IGS IGS 3D NAK 1E IRS IRS 3E 1F IUS IUS 3F 80 C A0 81 A / 82 B A2 83 C 84 TM SUB CC 5F ~ = 7F “ J C
Hex EBCDIC ASCII Hex EBCDIC ASCII Hex EBCDIC ASCII Hex EBCDIC ASCII 94 M _ B4 D4 M ( F4 4 PN 95 N > B5 D5 N + F5 5 RS 96 O ? B6 D6 O | F6 6 UC 97 P B7 D7 P & F7 7 EOT 98 Q B8 D8 Q F8 8 99 R B9 D9 R F9 9 9A ^ BA S DA FA 9B BB T DB FB 9C BC U DC 0 FC 9D BD ) DD 1 FD 9E BE W DE 2 FE BF X DF 3 FF 9F ; \ } ] HP StorageWorks P9000 Data Exchange User Guide 175
EBCDIC-ASCII Code Conversion
Glossary ALC Data Exchange Allocater utility. BL Block length. CC Code conversion. CKD Check key data. An IBM file structure standard for disk volumes. CR carriage return CU Control unit. CVS Custom volume size. DAM Direct-access method (not supported by Data Exchange). DAT Digital audio tape. DEL Delimiter option. DO Dataset organization. DS Dataset size. EA EBCDIC/ASCII (includes EBCDIC-to-ASCII and ASCII-to-EBCDIC). EBCDIC Extended binary-coded decimal interchange code.
FMT/ALC Formatter Allocater. FWD Fast-wide differential. FX Data Exchange. FXmto Data Exchange-mainframe to open. FXotm Data Exchange-open to mainframe. FXoto Data Exchange-open to open. HDLM Hitachi Dynamic Link Manager. HMBR HP Multiplatform Backup/Restore. ICKDSFA Device Support Facilities (DSF) command used to perform media maintenance. LD, LDEV Logical device.
SAM Sequential-access method, System Administration Manager (HP-UX). SIM Service information message. SMIT System Management Information Tool (IBM AIX). TID Target ID. V Variable-length and de-blocking (mainframe record format). VB Variable-length and blocking (mainframe record format). VIR Virtual LVI/LUN. volser Volume serial number. VSAM Virtual Storage Access Method (not supported by Data Exchange). VSE Virtual storage extended. VSN Volume serial number.
Glossary
Index A accessing FCU, 149 raw devices, 13 VSE datasets, 152 HP technical support, 172 Q queue depth, 57 C R commands deinstallation, 63 file menu, 83 help menu, 83 HRX file transfer operations, 17 Parameter Delete, 89, 93 Parameter Load, 89, 93 Parameter Save, 89, 93 Parameter-Save-Insert, 120 reserve, 36 TIME_OUT_VALUE, 24 View Status bar, 89 View Toolbar, 89 concurrent access support, 55 configuration illustration oto, 16 conventions storage capacity values, 171 related documentation, 171 reserve,
