ZPIO

Z-MAP Plus I/O Access Library
copyright 2002 by Landmark Graphics Corporation
625244 R2003.0 May 2002

Copyright 2002 by Landmark Graphics Corporation
All Rights Reserved Worldwide
This publication has been provided pursuant to an agreement containing restrictions on its use. The publication is also
protected by Federal copyright law. No part of this publication may be copied or distributed, transmitted, transcribed,
stored in a retrieval system, or translated into any human or computer language, in any form or by any means,
electronic, magnetic, manual, or otherwise, or disclosed to third parties without the express written permission of:
Landmark Graphics Corporation

Building 1, Suite 200, 2101 CityWest, Houston, Texas 77042, USA
P.O. Box 42806, Houston, Texas 77242, USA
Phone: 713-839-2000
Help desk: 713-839-2200
FAX: 713-839-2401
Internet: www.lgc.com
Trademark Notices
Landmark, the Landmark logo, 3D Drill View, 3D Drill View KM, 3DVIEW, Active Field Surveillance,
Active Reservoir Surveillance, ARIES, Automate, BLITZ, BLITZPAK, CasingSeat, COMPASS,
Contouring Assistant, DataStar, DBPlot, Decision Suite, Decisionarium, DecisionDesktop, DecisionSpace,
DepthTeam, DepthTeam Explorer, DepthTeam Express, DepthTeam Extreme, DepthTeam Interpreter, DESKTOP-
PVT, DESKTOP-VIP, DEX, DFW, DIMS, Discovery, Drillability Suite, DrillModel, DrillVision, DSS, Dynamic
Surveillance System, EarthCube, EdgeCa$h, eLandmark, EPM, e-workspace, FastTrack, FZAP!, GeoDataLoad,
GeoGraphix, GeoGraphix Exploration System, GeoLink, GES, GESXplorer, GMAplus, GrandBasin, GRIDGENR, I2
Enterprise, iDims, IsoMap, LandScape, LeaseMap, LMK Resources, LogEdit, LogM, LogPrep, Make Great
Decisions, MathPack, Model Builder, MyLandmark, MyWorkspace, OpenBooks, OpenExplorer, OpenJournal,
OpenSGM, OpenTutor, OpenVision, OpenWorks, OpenWorks Well File, PAL, Parallel-VIP, PetroBank, PetroWorks,
PlotView, Point Gridding Plus, Pointing Dispatcher, PostStack, PostStack ESP, PRIZM, PROFILE, ProMAX,
ProMAX 2D, ProMAX 3D, ProMAX 3DPSDM, ProMAX MVA, ProMAX VSP, pStaX, QUICKDIF, RAVE, Real
Freedom, Reservoir Framework Builder, RESev, ResMap, RMS, SafeStart, SCAN, SeisCube, SeisMap, SeisModel,
SeisSpace, SeisVision, SeisWell, SeisWorks, SeisXchange, SigmaView, SpecDecomp, StrataMap, Stratamodel,
StratAmp, StrataSim, StratWorks, StressCheck, STRUCT, SynTool, SystemStart, T2B, TDQ, TERAS, Total Drilling
Performance, TOW/cs, TOW/cs The Oilfield Workstation, Trend Form Gridding, Turbo Synthetics, VIP, VIP-COMP,
VIP-CORE, VIP-DUAL, VIP-ENCORE, VIP-EXECUTIVE, VIP-Local Grid Refinement, VIP-POLYMER, VIP-
THERM, WavX, Web OpenWorks, Well Editor, Wellbase, Wellbore Planner, WELLCAT, WELLPLAN,
WellXchange, wOW, Xsection, ZAP!, Z-MAP Plus are trademarks, registered trademarks or service marks of
Landmark Graphics Corporation.
All other trademarks are the property of their respective owners.
Note
The information contained in this document is subject to change without notice and should not be construed as a
commitment by Landmark Graphics Corporation. Landmark Graphics Corporation assumes no responsibility for any
error that may appear in this manual.
Landmark Graphics Z-MAP Plus I/O Access Library
Contents
Introduction .....................................................................................................................1
Purpose of This Guide ......................................................................................................1
What Is in This Guide .......................................................................................................2
Typographic Conventions.................................................................................................3
Related Documentation.....................................................................................................4
ZPI/O Overview ..............................................................................................................5

Introduction.......................................................................................................................5
Structure of Programs Using ZPI/O..................................................................................6
General Structure of Programs Using ZPI/O .............................................................6
Sequence of Calls to Read or Write a ZIMS File ......................................................7
Example Program for Listing Members of a Master File ..........................................8
Example Program for Creating Graphics .................................................................10
Example Program TSGRAP for Input Graphics ......................................................14
Subroutine Descriptions..................................................................................................25
Major ZPI/O Groupings ...........................................................................................25
Presentation of Information .....................................................................................25
Comments and Suggestions ............................................................................................29
Internal Routines ......................................................................................................29
Initializing Input Arguments ....................................................................................29
Calling Arguments ...................................................................................................29
Using the Debug Option, IDBUG ............................................................................29
Using the Status Flag Option, ISTAT ......................................................................30
Opening and Closing Files .......................................................................................30
Master File Numbers ................................................................................................31
Reading Sequential Data ..........................................................................................31
Writing Sequential Data ...........................................................................................31
Reading a File ..........................................................................................................32
Creating a File ..........................................................................................................32
Naming Output Data Files .......................................................................................33
Reading and Writing Grids ......................................................................................34
R2003.0 iii
Z-MAP Plus I/O Access Library Landmark Graphics
Initialize/Terminate ZPI/O Environment ..........................................................35

Internal Routines.............................................................................................................36
S2DBUG Reset the debug print flag ..........................................................................37
SICOMM Initialize the ZPI/O environment ...............................................................38
SIESIL Terminate the ZPI/O environment .............................................................39
SIEZIM Close a ZIMS file.......................................................................................40
SIISIL Initialize the ZPI/O environment with output file control .........................41
Transfer, Convert, or List Information .............................................................43

Introduction.....................................................................................................................43
S2FLIN Transfer information from an external file into a member of a master file44
S2GRST Compute grid file statistics ........................................................................46
S4CDTR Convert from x,y to latitude/longitude and vice versa ...............................49
SICTST Compute control point file statistics ..........................................................56
SIFDST Compute statistics for a field .....................................................................59
SIFLOT Transfer information from a member of a master file to an external file ..61
SIGLST List a grid as a grid or contours .................................................................63
SILIST List a data file.............................................................................................66
Draw and Plot Features ...........................................................................................69

S2ALIN Draw lines using array inputs ....................................................................70
S2DSPT Display a picture or plot a hardcopy of a picture.......................................72
S3ZLIN Draw lines using a member file .................................................................74
iv Contents R2003.0
Graphics Utilities ........................................................................................................77

S2GMRK Draw markers.............................................................................................78
S2ZGIN Transfer the contents (pictures) of a neutral file to a graphics file ............79
S2ZGOT Transfer a set of pictures from a graphics file to a neutral file ..................80
S3GELM Obtain the next valid graphics element from a picture ..............................81
S3IPIC Open a new or old picture..........................................................................85
S3NPIC Open a new picture ....................................................................................92
S3OPIC Open an old picture..................................................................................101
S4PCIN Obtain general, projection and graphics feature information
for a picture ..............................................................................................109
SIEPIC Close the last picture opened ...................................................................117
SIEZGF Close a graphics file.................................................................................118
SIEZIG Terminate the Z-MAP Interactive Graphics Environment (ZIGS)..........119
SIGLCL Set line color ............................................................................................120
SIGLIN Draw connected line segments.................................................................121
SIGLPM Set dash line and hachure mark parameters.............................................122
SIGLTY Set line type..............................................................................................123
SIGLWD Set line width ...........................................................................................124
SIGMCL Set marker color.......................................................................................125
SIGMHT Set marker height .....................................................................................126
SIGMTY Set marker type ........................................................................................127
SIGPCL Set polygon fill color ...............................................................................128
SIGPDF Set defaults for lines, markers, text, and polygons ..................................129
SIGPFL Draw a shaded or colorfilled polygon......................................................132
SIGSCL Close current graphics feature .................................................................133
SIGSCS Define coordinate system.........................................................................134
SIGSDL Delete a graphics feature from a picture file............................................135
SIGSOP Open a new graphics feature....................................................................136
SIGTCL Set text color ............................................................................................137
SIGTFO Set text font ..............................................................................................138
SIGTHT Set text height ..........................................................................................139
SIGTJU Set text justification .................................................................................140
SIGTRO Set text rotation ........................................................................................141
SIGTXT Draw text..................................................................................................142
SIIZGF Open a graphics file .................................................................................145
R2003.0 Contents v
SIIZIG Initialize the Z-MAP Interactive Graphics Environment (ZIGS) ............146

SIOVLY Overlay maps or generate index maps .....................................................147
SIPCAS Assemble/overlay a picture......................................................................149
SIPCCP Copy all or part of a picture to another picture........................................153
SIPCDF Compute four corners of one picture relative
to another picture for assembly/overlay...................................................155
SIPCDL Mark a picture for deletion ......................................................................159
SIPCFL Obtain a picture name by picture index ...................................................160
SIPCRN Rename a picture......................................................................................161
SIRPIC Open an old picture in read-only mode....................................................162
SIZGCM Compress a graphics file..........................................................................163
SOGCLS Obtain the color representation for a color index ....................................165
SOGEND Terminate the ZPI/O output graphics environment .................................166
SOGINT Initialize the ZPI/O output graphics environment ...................................167
SOGLGB Obtain the next graphics feature for the picture.......................................168
File Utilities ..................................................................................................................169

Internal Routines...........................................................................................................169
S2DELE Delete a member file from a master file ..................................................170
S2FLST List member files .....................................................................................171
S2IZIM Initialize the Z-MAP Information Management System (ZIMS)
and attach master files..............................................................................173
S2LHIS List the history and ancestry of a member file.........................................175
S2MFAT Attach a master file indicating either read-only or read-write file access177
S5DAFU Obtain parameter, projection, and field information about a data file.....178
SIDFFD Set default field descriptors .....................................................................184
SIDNFL Retrieve information about a member file from the runtime directory ...187
SIEZIM Close master files.....................................................................................188
SIFCLO Close a member file .................................................................................189
SIFLDR Read a field descriptor .............................................................................190
SIFLDW Write a field descriptor ............................................................................192
SIFRED Read a record from a member file ...........................................................194
SIFWRT Write a record to a member file ...............................................................195
SIIZIM Initialize the Z-MAP Information Management System (ZIMS)
and attach master files..............................................................................197
vi Contents R2003.0
SIMFAT Attach a master file ..................................................................................198

SIMFCM Compress a master file.............................................................................199
SIMFCR Create a new master file...........................................................................200
SIMFDT Detach one or all master files...................................................................202
SIMFLS List attached master files .........................................................................203
SIMFRN Rename the internal name of a master file...............................................204
SINOPN Open a new member file ..........................................................................205
SIOOPN Open an old member file..........................................................................206
SIPRRC Read a general data or contour parameter record ....................................207
SIPRRD Read a data parameter record...................................................................209
SIPRRG Read a grid parameter record...................................................................210
SIPRWC Write a general data or contour parameter record ...................................211
SIPRWD Write a data parameter record..................................................................213
SIPRWG Write a grid parameter record ..................................................................214
SIRDPO Position a member file for a sequential read............................................215
SIRDRN Read from a member file at a random location........................................216
SIRDSQ Read from a member file sequentially .....................................................217
SIRHIS Read history information from a member file .........................................218
SIWHIS Write history records to a member file ....................................................219
SIWRPO Position a member file for a sequential write ..........................................220
SIWRRN Write to a member file at a random location ...........................................221
SIWRSQ Write to a member file sequentially.........................................................222
Appendix A. ZIGS Overview ...............................................................................223

ZIGS File Structure.......................................................................................................223
Picture Components ...............................................................................................223
Headers ..................................................................................................................224
ZIGS Programmers Guide ...........................................................................................226
Input Graphics to a Picture ....................................................................................226
Output Graphics from a Picture .............................................................................233
R2003.0 Contents vii

Appendix B. ZIMS Overview ...............................................................................235

ZIMS File Structure ......................................................................................................236
Master File .............................................................................................................236
Member File ...........................................................................................................237
ZIMS Programmers Guide ..........................................................................................241
Creating a Member File .........................................................................................241
Reading Data from an Existing ZIMS File ............................................................244
Reading and Writing Grids ....................................................................................246
Appendix C. Logical Unit Assignment .........................................................247
Index ................................................................................................................................252
viii Contents R2003.0

Introduction
Overview
The Z-MAP Plus I/O Access Library (referred to as ZPI/O) is a set of

FORTRAN-callable subroutines that can be linked into a non-
Landmark program to perform functions available in Z-MAP Plus. The
input control parameters are essentially the same as those required if
the modules are used in Z-MAP Plus, and the results are identical since
the same processing code is used in either case. Therefore, information
generated by Z-MAP Plus or by the user-written program can be used
interchangeably.
This guide describes how to use ZPI/O in custom programs. Each of the
ZPI/O subroutines is documented with appropriate programming notes.
Sample programs are included, as are step-by-step guides for graphics
and file management programming.
Purpose of This Guide
This guide describes how to use the ZPI/O Access Library in custom
programs. Each of the ZPI/O subroutines is documented with
appropriate programming notes.
The guide is intended to be read by experienced programmers who are

accustomed to working with large-scale FORTRAN programs,
particularly those relating to mapping and modeling geoscience data.
1 Introduction: Purpose of This Guide R2003.0

What Is in This Guide
This programmers guide provides information about each of the

following topics:
Introduction (page 1) explains the purpose of this guide, who

should read it, what is contained in it, what some of the
conventions used are, and how to find more information.
ZPI/O Overview (page 5) explains what the Z-MAP Plus I/O

Access Library is, how the subroutine descriptions are structured,
and how some of the most frequently used subroutines work.
Sample programs and suggestions are also presented.
Initialize/Terminate ZPI/O Environment (page 35) lists the

subroutines used for initializing and terminating the ZPI/O
environment.
Transfer, Convert, or List Information (page 43) lists the

subroutines used for converting data from one format to another,
generating lists and reports, computing statistics for files, and
transferring data between disk files and master files.
Draw and Plot Features (page 69) lists the subroutines used for
drawing lines from an array or member file, and displaying or
plotting a picture.
Graphics Utilities (page 77) lists the subroutines used for

initializing and terminating the graphics environment, attaching
and detaching graphics files, opening and closing pictures,
designing and creating pictures from basic elements, and
extracting graphics elements.
File Utilities (page 169) lists subroutines used for initializing the
information management environment; opening and closing
master files; attaching, compressing, creating, detaching and
listing master files; renaming the internal name of a master file;
opening, closing, deleting, listing, reading, writing, and obtaining
information from member files; positioning member files; and
reading, writing, and setting defaults for field descriptors.
Appendix A. ZIGS Overview (page 223) explains the file

structure of the Zycor Interactive Graphics System (ZIGS) and
steps for using ZIGS in ZPI/O application programs.
R2003.0 Introduction: What Is in This Guide 2

Appendix B. ZIMS Overview (page 235) explains the file

structure of the Zycor Information Management System (ZIMS)
and steps for using ZIMS in ZPI/O application programs.
Appendix C. Logical Unit Assignment (page 247) lists the

logical FORTRAN units used throughout ZPI/O.
The Index (page 252) references the function of the subroutines,

such as write or terminate, and the objects that are acted on, such
as master file or line.
Typographic Conventions
To make the information in this guide as accessible as possible, the

following conventions are observed throughout:
Examples of text you type in or text displayed on the screen are in

a typewriter-style font, such as:
****** SIISIL - ERROR, PROBLEM OPENING FILES
A portion of an example of text you type in that is to be replaced

by a user value is presented in italic typewriter-style font, such as:
COMMON/WRKSPC/IWORK(n)
Some acronyms and abbreviations are used throughout this guide:
ZPI/O Z-MAP Plus I/O Access Library

ZIGS Zycor Interactive Graphics System
ZIMS Zycor Information Management System
LGB logical graphics block, known in Z-MAP Plus as
graphics feature
ZGF Zycor graphics file
MFD Zycor master file
in or cm inches or centimeters, alternative measurements for
plotter units
3 Introduction: Typographic Conventions R2003.0

Related Documentation
The following guides are available from your system administrator or

Landmark representative.
Z-MAP Plus Installation and Configuration
Each of these guides contains appendixes with information you may

find useful for structuring a custom program.
ZCL Operators Manual presents the Zycor Command Language

ZCL) and shows you how to start the program and use process
statements to write a command stream for generating a variety of
maps. The ZCL Operators Manual covers all parameters for all
processes available in ZCL.
Z-MAP Plus Reference Guide provides easy access to reference

information about the tasks and subtasks of the Z-MAP Plus
program. Overview workflows, tables, and selected screen
captures supplement the text to assist you in understanding how to
use each task.
R2003.0 Introduction: Related Documentation 4

ZPI/O Overview
Introduction
The Z-MAP Plus I/O Access Library (referred to as ZPI/O) is a set of

FORTRAN-callable subroutines that can be linked into a
non-Landmark program to perform functions available in Z-MAP Plus.
The input control parameters are essentially the same as those required
if the modules are used in Z-MAP Plus, and the results are identical
since the same processing code is used in either case. Therefore,
information generated by Z-MAP Plus or by the user-written program
can be used interchangeably.
The routines included in the ZPI/O Access Library are compiled under
FORTRAN 77. Every reasonable effort has been made to minimize
system dependenciesif they do exist, they are localized.
This section contains information about the following topics:
Structure of Programs Using ZPI/O (page 6) outlines the

general structure of programs using ZPI/O and presents example
programs for listing members of a master file, creating simple
graphics, and testing the input graphics routines.
Subroutine Descriptions (page 25) describes the presentation of

the subroutines.
Comments and Suggestions (page 29) includes general

information about ZPI/O and the debug and status flag options,
and suggestions for programming basic procedures.
5 ZPI/O Overview: Introduction R2003.0

Structure of Programs Using ZPI/O
To help you write a program using ZPI/O routines, this topic includes
an outline of the general structure of a program and an example
program.
General Structure of Programs Using ZPI/O

The following outline briefly describes the structure of a program
which uses ZPI/O. This should serve as a guide and not as a fixed
structure, but the general sequence of events must be preserved for
ZPI/O to function properly.
I. Initialization
A. Initialize the ZPI/O environment SICOMM or SIISIL
B. ZIMS initialization, initialize master files SIIZIM
C. ZIGS initialization SIIZIG
II. File Utilities
A. Open new dataset SINOPN
B. Write field descriptors SIFLDW
C. Read data SIFRED
D. Write data SIFWRT
E. Write parameter record SIPRWD, SIPRWG or SIPRWC
F. Close dataset SIFCLO
III. Graphics Features
A. Open graphics file SIIZGF
B. Open picture S3IPIC, S2NPIC, S2OPIC or SIRPIC
C. Graphics Draw and Plot Features or Graphics Utilities
D. Close picture SIEPIC
E. Close graphics file SIEZGF
IV. Termination
A. Close graphics SIEZIG
B. Terminate ZPI/O environment SIIESIL
R2003.0 ZPI/O Overview: Structure of Programs Using ZPI/O 6

Sequence of Calls to Read or Write a ZIMS File

Typical sequence of calls to write and read a ZIMS file.
Writing:
SINOPN to create and open the file

SIWRPO to make sure file is positioned correctly, IWORD=1
SIWRSQ repeatedly to write data. Usually NWORDS is same as
record size.
alternatively SIFWRT or SIWRRN can sometimes be useful
after all data is written:
SIFLDW for each field of a data file

SIPRWD write a parameter record, SIPRWG if this is a grid file
except that if this file has more than 24 fields, the field descriptors
must be written before any data is written (SIFLDW) but can be
written with dummy data then overwritten. SIWRPO should be
called before calls to SIWRSQ.
SIFCLO close file, update MFD headers
Reading:
SIOOPN to open existing file

SIPRRD to read the parameter record (SIPRRG for grids)
SIFLDR can be used to read field descriptors (name of fields, etc.)
before or after the data (or any time) but the file may need to be
repositioned with SIRDPO. This info may not be needed and the
calls can be skipped
SIRDPO with IWORD=1 to make sure file is positioned correctly
typically a loop reading NRECS (from SIPRRD) records of
NWORDS (from SIPRRD) words each is performed using
SIRDSQ to read data
alternatively SIRDRN or SIFRED may be used
for grids, you may want to loop on NCOLS and NROWS from
SIPRRG
SIFCLO to close the file and free up the buffer, only 5 of which
are available
R2003.0 ZPI/O Overview: Sequence of Calls to Read or Write a ZIMS File 7

Example Program for Listing Members of a Master File

This short example program illustrates the minimum that must be done
to work with master files (MFDs). This program assumes that an MFD
was created elsewhere. It does the necessary initialization, then lists the
contents of the MFD. It then lists the contents of one file. It assumes
that the name of the file is known. (For example, the listing just done
gives the name of the file.)
This example is written on a Unix system and assumes that variables

not explicitly initialized are set to zero.
C
C SAMPLE ZPIO PROGRAM TO LIST A MEMBER FILE
C
COMMON /WRKSPC/IWORK(30000)
C
CHARACTER *80 NAMMFD(4)
C
DATA IDBUG /1/
C VARIABLES FOR S2FLST
CHARACTER * 7 REPORT
CHARACTER *24 NAME
CHARACTER *4 TYPES
LOGICAL BYNAME, BYTYPE
C VARIABLES FOR SILIST
CHARACTER *24 NAMIDA
CHARACTER *80 RPTITL
CHARACTER *20 ICLHDR(10)
CHARACTER *20 IFDFMT(10)
C
C INITIALIZE SYSTEM-WIDE COMMON STORAGE
C
IDBUG = 0
LTHWRK = 30000
LUNINF = 6
LUNSTA = 6
LUNWAR = 6
LUNERO = 6
LUNBUG = 6
IPROC = 0
CALL SIISIL(IDBUG, LTHWRK, LUNINF, LUNSTA, LUNWAR,
. LUNERO, LUNBUG, LUNDM1, LUNDM2, IPROC, ISTAT)
C
C INITIALIZE ZIMS
C NAME OF MFD TO ATTACH
C NON UNIX SYSTEMS MAY NAME THE MFD IN A DIFFERENT MANNER
NAMMFD(1) = /zplus1/users/wow/zpio/zpio.mfd
MFDNUM = 1
LUNDRC = 20
CALL SIIZIM(NAMMFD, MFDNUM, LUNDRC, ISTAT)
8 ZPI/O Overview: Example Program for Listing Members of a Master File R2003.0
C
C LIST FILES ON MFD
REPORT = SUMMARY
NAME =
TYPES =
BYNAME = .FALSE.
BYTYPE = .FALSE.
NUMTYP = 0
LUNRPT = 0
C S2FLST DOESNT INITIALIZE ISTAT
ISTAT = 0
CALL S2FLST(REPORT, NAME, TYPES, BYNAME, BYTYPE, NUMTYP,
X LUNRPT, ISTAT)
IF (ISTAT .NE. 0) WRITE(LUNBUG, 20) ISTAT
20 FORMAT( ZPIO DEMO S2FLST RETURNS ISTAT OF ,I5)
C
C LIST A DATA FILE (ASSUME UNITIALIZED VARIABLES ARE ZERO)
C THIS NAME FOR A FILE COULD BE GOTTEN FROM THE PREVIOUS LISTING
NAMIDA = well data
RPTITL = sample report
DO 30 I=1,10
ICLHDR(I) =
IFDFMT(I) =
30 CONTINUE
MFDIDA = 1
LOGRPT = 6
ISTART = 1
CALL SILIST(NAMIDA, RPTITL, LINARA, ICLHDR, IFDFMT, MFDIDA,
1 IHISDA, LOGRPT, NUMLIN, LSTTYP, ISTART, IEND, NUMFLD,
2 ICLWID, IFDINX, IWDINX, WIDMIN, WIDMAX, ISTAT)
IF (ISTAT .NE. 0) WRITE(LUNBUG, 40) ISTAT
40 FORMAT( ZPIO DEMO SILIST RETURNS ISTAT OF ,I5)
C
C TERMINATION
CALL SIESIL(ISTAT)
C REMOVE LOCK FILES FOR MFDS (FOR UNIX SYSTEMS)
CALL SIEZIM
STOP
END
R2003.0 ZPI/O Overview: Example Program for Listing Members of a Master File 9
Example Program for Creating Graphics

This is a short example of creating graphics. A graphics file and picture
are created, and a few lines and some short text is displayed.
This was created on a Unix system, and assumes that uninitialized

variables are set to zero.
The results could be viewed in a Landmark program such as

Z-MAP Plus or plotted on a hardcopy device.
C
C SAMPLE ZPIO PROGRAM TO DRAW SIMPLE GRAPHICS
C THE CREATED ZGF CAN BE DISPLAYED WITH OTHER LANDMARK PRODUCTS
C OR PLOTTED TO A HARDCOPY DEVICE.
C ASSUMES UNINITIALIZED VARIABLES ARE SET TO ZERO.
C
COMMON /WRKSPC/IWORK(30000)
C
C TURN DEBUG PRINTS ON OR OFF
DATA IDBUG /1/
C
C VARIABLES FOR SIIZGF
CHARACTER * 80 ZGFNAM
CHARACTER * 80 HISNEW, HISOLD
CHARACTER * 3 NEWZGF
C VARIABLES FOR S3IPIC
CHARACTER * 80 PICNAM
CHARACTER * 3 IFOLD
DOUBLE PRECISION VXMIN, VXMAX, VYMIN, VYMAX
C VARIABLES FOR SIGLIN
DIMENSION XCORS(10), YCORS(10)
C VARIABLE FOR SIGTXT
CHARACTER *80 TEXT
C
C
C IDBUG = 0
LTHWRK = 30000
LUNINF = 6
LUNSTA = 6
LUNWAR = 6
LUNERO = 6
LUNBUG = 6
IPROC = 0
C
CALL SIIZIG
10 ZPI/O Overview: Example Program for Creating Graphics R2003.0

C
C CREATE AND OPEN A ZGF
C FOR NON UNIX SYSTEMS, THIS MAY LOOK DIFFERENT
ZGFNAM = /zplus1/users/wow/zpio/zpio.zgf
NEWZGF = NEW
HISNEW = TESTING ZPIO INPUT GRAPHICS ROUTINES
C
CALL SIIZGF (ZGFNAM, HISNEW, NEWZGF, HISOLD, ISTAT)
IF (ISTAT .GT. 0) THEN
WRITE(LUNBUG, 100) ISTAT
100 FORMAT(zpiodraw siizgf returns istat ,i5)
GO TO 800
END IF
C
C OPEN A NEW PICTURE
PICNAM = HELLO WORLD ON A PICTURE
IFOLD = NEW
IFABSC = 0
IFPRJ = 1
IBRTIP = 2
XOFFST = 1.0
FREEX = 1.0
YOFFST = 1.0
FREEY = 1.0
VXMIN = 0.0
VXMAX = 10.0
VYMIN = 0.0
VYMAX = 10.0
XSCMAP = 1.0
YSCMAP = 1.0
XLONG = 10.0
YLONG = 10.0
C
CALL S3IPIC (PICNAM, IFOLD, IFABSC, IFPRJ, IBRTIP,
1 IABSSC, LONMND, LONMNM, LONMNS, LONMXD,
2 LONMXM, LONMXS, LATMND, LATMNM, LATMNS,
3 LATMXD, LATMXM, LATMXS, IHEM, IUTMCD,
4 IPJCOD, ISPCOD, IUNCOD, IRADTY VXMIN,
5 VXMAX, VYMIN, VYMAX, XOFFST, FREEX,
6 YOFFST, FREEY, XSCMAP, YSCMAP, XLONG,
7 YLONG, BOTPAR, TOPPAR, REFLAT, SFLAT,
8 REFLON, SFLON, FNORTH, FEAST, UNTFAC,
9 AXISA, AXISB, AZMTH, SCALE, XLNVEW,
. YLNVEW, ISTAT )
200 FORMAT(ZPIODRAW S3IPIC RETURNS ISTAT OF ,I5)
GO TO 800
END IF
C
C OPEN PICTURE SEGMENT
R2003.0 ZPI/O Overview: Example Program for Creating Graphics 11

C
LGBTYP = 1
CALL SIGSOP(LGBTYP, ISTAT)
350 FORMAT(ZPIODRAW SIGSOP RETURNS ISTAT OF ,I5)
GO TO 800
END IF
C
C SET DEFAULTS
C
KTXTCL = 7
KIXTJU = 3
KTXTFO = 2
HTTEXT = .5
CALL SIGPDF(
1 KLNCLR, KLNTYP, KMKCLR, KMKTYP, KTXTCL,
2 KTXTFO, KTXTJU, KPOLCL, KSCLTY, WDLINE,
3 HTMARK, HTTEXT, ROTEXT, DSHLEN, DSHGAP,
4 HSHLEN, HSHGAP, HSHWAY, ISTAT)
300 FORMAT(ZPIODRAW SIGPDF RETURNS ISTAT OF ,I5)
GO TO 800
END IF
C
C DRAW A BORDER USING LINES
C
NUMPTS = 5
XCORS(1) = 1.0
YCORS(1) = 1.0
XCORS(2) = 11.0
YCORS(2) = 1.0
XCORS(3) = 11.0
YCORS(3) = 11.0
XCORS(4) = 1.0
YCORS(4) = 11.0
XCORS(5) = 1.0
YCORS(5) = 1.0
CALL SIGLIN(NUMPTS, XCORS, YCORS, ISTAT )
360 FORMAT(ZPIODRAW SIGLIN RETURNS ISTAT OF ,I5)
END IF
C
12 ZPI/O Overview: Example Program for Creating Graphics R2003.0

C DRAW TEXT
C
NUMCHR = 11
XCORS(1) = 4.0
YCORS(1) = 5.0
TEXT = HELLO WORLD
CALL SIGTXT(TEXT, NUMCHR, XCORS(1), YCORS(1), ISTAT )
IF (ISTAT .GT. 0) WRITE(LUNBUG, 370) ISTAT
370 FORMAT(ZPIODRAW: SIGTXT ISTAT,I3, GRAPHICS FEATURE NOT
OPEN)
C
C CLOSE GRAPHIC SEGMENT
C
CALL SIGSCL(ISTAT)
400 FORMAT(ZPIODRAW SIGSCL RETURNS ISTAT OF ,I5)
END IF
C
800 CONTINUE
C CLOSE THE PICTURE
C
CALL SIEPIC (ISTAT)
500 FORMAT(ZPIODRAW SIEPIC ISTAT,I5, ERROR CLOSING PICTURE)
END IF
C
C TERMINATION
CALL SIESIL(ISTAT)
STOP
END
R2003.0 ZPI/O Overview: Example Program for Creating Graphics 13

Example Program TSGRAP for Input Graphics

The results of this example program could be plotted on a hardcopy
device or displayed in a Landmark program such as Z-MAP Plus.
C PURPOSE: TEST THE INPUT GRAPHICS ROUTINES

C
COMMON /WRKSPC/ IWORK(30000)
C
CHARACTER *6 NAMRET
PARAMETER (NAMRET = TSGRAP)
C
CHARACTER *80 ZGFNAM, HISNEW, PICNAM, NAMMFD (4), HISOLD
CHARACTER *24 NAMZIM, ZNAME
CHARACTER * 3 IFOLD, NEWZGF
CHARACTER *20 TEXT
C
DOUBLE PRECISION VXMIN, VXMAX, VYMIN, VYMAX
C
DIMENSION XCORS(10), YCORS(10)
C
DATA NOMFDS/1/, LUNDIR/20/, LTHWRK/30000/, IDBUG /1/, IPROC/
0/
DATA LUNINF/6/, LUNSTA/6/, LUNWAR/6/, LUNERO/6/, LUNBUG/6/
DATA LUNDM1/0/, LUNDM2/0/
C
WRITE(LUNBUG,9992)
9992 FORMAT(//,25X, THIS ROUTINE TESTS ,/,
. TEST THE INPUT GRAPHICS ROUTINES )
C
C
C
CALL SIIZIG
C
C IFNEW - 0, OLD GRAPHICS FILE
C - 1, NEW GRAPHICS FILE
C XOFSET - BORDER WIDTH AROUND LEFT OF MAP. UNITS PER INCH.
C XFREE - BORDER WIDTH AROUND RIGHT OF MAP. UNITS PER INCH.
C YOFSET - BORDER WIDTH BELOW MAP, UNITS/INCH.
C YFREE - BORDER WIDTH ABOVE MAP, UNITS/INCH.
C XVEWLN = XOFSET+XLENGH+XFREE (OUTPUT ONLY)
C YVEWLN = YOFSET+YLENGH+YFREE (OUTPUT ONLY)
C
IF(IDBUG .EQ. 1) WRITE(LUNBUG, 1001)
1001 FORMAT(15X, ****** BEGINNING OF PICTURE ONE ****** )
C
C ON A NON UNIX SYSTEM, THIS MAY LOOK DIFFERENT
ZGFNAM = /zplus1/users/wow/zpio/TSGRAP.ZGF
NEWZGF = NEW
C
IF (ISTAT .GT. 0) GO TO 800
14 ZPI/O Overview: Example Program TSGRAP for Input Graphics R2003.0

C
PICNAM = DEFAULT GRAPHICS
IFOLD = NEW
IFABSC = 0
IFPRJ = 1
IBRTIP = 2
IABSSC = 0
LONMND = 0
LONMNM = 0
LONMNS = 0
LONMXD = 0
LONMXM = 0
LONMXS = 0
LATMND = 0
LATMNM = 0
LATMNS = 0
LATMXD = 0
LATMXM = 0
LATMXS = 0
IHEM = 0
IUTMCD = 0
IPJCOD = 0
ISPCOD = 0
IUNCOD = 0
IRADTY = 0
XOFFST = 1.0
FREEX = 1.0
YOFFST = 1.0
FREEY = 1.0
VXMIN = 0.0
VXMAX = 10.0
VYMIN = 0.0
VYMAX = 10.0
XSCMAP = 1.0
YSCMAP = 1.0
XLONG = 10.0
YLONG = 10.0
BOTPAR = 0.0
TOPPAR = 0.0
REFLAT = 0.0
SFLAT = 0.0
REFLON = 0.0
SFLON = 0.0
FNORTH = 0.0
FEAST = 0.0
UNTFAC = 0.0
AXISA = 0.0
AXISB = 0.0
AZMTH = 0.0
SCALE = 0.0
XLNVEW = 0.0
YLNVEW = 0.0
R2003.0 ZPI/O Overview: Example Program TSGRAP for Input Graphics 15

C
4 IPJCOD, ISPCOD, IUNCOD, IRDATY VXMIN,
. YLNVEW, ISTAT )
C
C SET DEFAULTS
C
CALL SIGPDF(
C
C OPEN BORDER PICTURE SEGMENT
C
LGBTYP = 1
C
C DO A BORDER USING LINES
C
NUMPTS = 5
XCORS(1) = 1.0
YCORS(1) = 1.0
XCORS(2) = 11.0
YCORS(2) = 1.0
XCORS(3) = 11.0
YCORS(3) = 11.0
XCORS(4) = 1.0
YCORS(4) = 11.0
XCORS(5) = 1.0
YCORS(5) = 1.0
C
C
C
CALL SIGSCL(ISTAT)
C
C OPEN POLYGON LINES PICTURE SEGMENT
C
LGBTYP = 7
C
C DO A MARKERS AND LINES USING LINES

C
NUMMRK = 3
XCORS(1) = 2.0
YCORS(1) = 6.0
XCORS(2) = 10.0
YCORS(2) = 6.0
XCORS(3) = 6.0
YCORS(3) = 10.0
C
CALL SIGMRK(NUMMRK, XCORS, YCORS, ISTAT )
C
NUMPTS = 2
XCORS(1) = 2.50
YCORS(1) = 6.0
XCORS(2) = 9.50
YCORS(2) = 6.0
XCORS(1) = 9.50
YCORS(1) = 6.50
XCORS(2) = 6.50
YCORS(2) = 9.50
XCORS(1) = 5.50
YCORS(1) = 9.50
XCORS(2) = 2.50
YCORS(2) = 6.50
C
C
CALL SIGSCL(ISTAT)
C
C OPEN TEXT PICTURE SEGMENT
C
LGBTYP = 6
C
C DO TEXT
C
NUMCHR = 20
XCORS(1) = 3.0
XCORS(1) = 5.50
YCORS(1) = 9.50
XCORS(2) = 2.50
YCORS(2) = 6.50
C

C
CALL SIGSCL(ISTAT)
C
C
LGBTYP = 6
C
C DO TEXT
C
NUMCHR = 20
XCORS(1) = 3.0
YCORS(1) = 5.0
TEXT = TEST INPUT GRAPHICS
C 123456789 123456789
C
C
NUMCHR = 4
XCORS(1) = 5.50
YCORS(1) = 7.0
TEXT = HI!
C
C
C
CALL SIGSCL(ISTAT)
C
C OPEN POLYGON FILE PICTURE SEGMENT
C
LGBTYP = 30
C
C
NUMVTX = 5
XCORS(1) = 4.50
YCORS(1) = 6.50
XCORS(2) = 7.50
YCORS(2) = 6.50
XCORS(3) = 7.50
YCORS(3) = 8.0
XCORS(4) = 4.50
YCORS(4) = 8.0
XCORS(5) = 4.50
YCORS(5) = 6.50
write(6, 133)
133 format( a )

C
CALL SIGPFL(NUMVTX, XCORS, YCORS, ISTAT )
C
C
CALL SIGSCL(ISTAT)
C
C CLOSE THE FIRST PICTURE
C
CALL SIEPIC (ISTAT)
IF (ISTAT .NE. 0) GO TO 800
C
IF(IDBUG .EQ. 1) THEN
WRITE(LUNBUG,1002)
1002 FORMAT(15X, ***** END OF FIRST PICTURE ****** )
WRITE(LUNBUG, 2001)
2001 FORMAT(15X, ***** BEGINNING OF SECOND PICTURE ****** )
ENDIF
C
PICNAM = SETTING GRAPHICS
IFOLD = NEW
IFABSC = 0
IFPRJ = 1
IBRTIP = 2
IABSSC = 0
LONMND = 0
LONMNM = 0
LONMNS = 0
LONMXD = 0
LONMXM = 0
LONMXS = 0
LATMND = 0
LATMNM = 0
LATMNS = 0
LATMXD = 0
LATMXM = 0
LATMXS = 0
IHEM = 0
IUTMCD = 0
IPJCOD = 0
ISPCOD = 0
XOFFST = 1.0
FREEX = 1.0
YOFFST = 1.0
FREEY = 1.0
IRADTY = 0
VXMIN = 0.0
VXMAX = 10.0
VYMIN = 0.0
VYMAX = 10.0
XSCMAP = 1.0
YSCMAP = 1.0
XLONG = 10.0
YLONG = 10.0
BOTPAR = 0.0
TOPPAR = 0.0
REFLAT = 0.0
SFLAT = 0.0

REFLON = 0.0
SFLON = 0.0
FNORTH = 0.0
FEAST = 0.0
UNTFAC = 0.0
AXISA = 0.0
AXISB = 0.0
AZMTH = 0.0
SCALE = 0.0
XLNVEW = 0.0
YLNVEW = 0.0
C
4 IPJCOD, ISPCOD, IUNCOD, IRADTY VXMIN,
. YLNVEW, ISTAT )
C
C SET DEFAULTS
C
CALL SIGPDF(
C
C
LGBTYP = 1
C
C SET SPECIAL LINE PARAMETERS
C
DSHLEN = 0.4
DSHGAP = 0.2
HSHLEN = 0.1
HSHGAP = 0.2
HSHWAY = -1.0
CALL SIGLPM( DSHLEN, DSHGAP, HSHLEN, HSHGAP, HSHWAY, ISTAT)
IF(ISTAT .GT. 0) GO TO 800
C
C SET LINE COLOR, LINE TYPE, AND LINE WIDTH

C
IRED = 2
CALL SIGLCL(IRED, ISTAT)
LDASH = 2
CALL SIGLTY(LDASH, ISTAT)
WIDTH = 4.0
CALL SIGLWD(WIDTH, ISTAT)
C
C
NUMPTS = 5
XCORS(1) = 1.0
YCORS(1) = 1.0
XCORS(2) = 11.0
YCORS(2) = 1.0
XCORS(3) = 11.0
YCORS(3) = 11.0
XCORS(4) = 1.0
YCORS(4) = 11.0
XCORS(5) = 1.0
YCORS(5) = 1.0
C
C
C
CALL SIGSCL(ISTAT)
C
C OPEN POLYGON LINES PICTURE SEGMENT
C
LGBTYP = 7
C
C SET MARKER COLOR, MARKER HEIGHT
C
IGREEN = 3
CALL SIGMCL(IGREEN, ISTAT)
HGTMRK = 0.3
CALL SIGMHT(HGTMRK, ISTAT)
C
C DO A MARKERS AND LINES USING LINES
C
NUMMRK = 3
XCORS(1) = 2.0
YCORS(1) = 6.0
XCORS(2) = 10.0
YCORS(2) = 6.0
XCORS(3) = 6.0
YCORS(3) = 10.0
ROTATE = 0.0

C
CALL S2GMRK(NUMMRK, XCORS, YCORS, ROTATE, ISTAT )
C
C SET LINE COLOR, TYPE, WIDTH
C
IYELL = 7
CALL SIGLCL(IYELL, ISTAT)
LHACH = 3
CALL SIGLTY(LHACH, ISTAT)
WIDTH = 2
CALL SIGLWD(WIDTH, ISTAT)
C
NUMPTS = 2
XCORS(1) = 2.50
YCORS(1) = 6.0
XCORS(2) = 9.50
YCORS(2) = 6.0
XCORS(1) = 9.50
YCORS(1) = 6.50
XCORS(2) = 6.50
YCORS(2) = 9.50
XCORS(1) = 5.50
YCORS(1) = 9.50
XCORS(2) = 2.50
YCORS(2) = 6.50
C
C
CALL SIGSCL(ISTAT)
C
C
LGBTYP = 6
C
C SET TEXT COLOR, FONT, HEIGHT, JUSTIFICATION, ANGLE

C
ICYAN = 5
CALL SIGTCL(ICYAN, ISTAT)
TXTHGT = 0.5
CALL SIGTHT(TXTHGT, ISTAT)
JUSTCT = 3
CALL SIGTJU(JUSTCT, ISTAT)
IATLIC = 4
CALL SIGTFO(IATLIC, ISTAT)
TXTANG = 45.0
CALL SIGTRO(TXTANG, ISTAT)
C
C DO TEXT
C
NUMCHR = 20
XCORS(1) = 3.0
YCORS(1) = 5.0
TEXT = TEST INPUT GRAPHICS
C 123456789 123456789
C
C
C
C SET TEXT COLOR, FONT, HEIGHT, JUSTIFICATION, ANGLE
C
MAGENT = 6
CALL SIGTCL(MAGENT, ISTAT)
TXTHGT = 0.2
CALL SIGTHT(TXTHGT, ISTAT)
JUSTRT = 2
CALL SIGTJU(JUSTRT, ISTAT)
IROMAN = 3
CALL SIGTFO(IROMAN, ISTAT)
TXTANG = 270.0
CALL SIGTRO(TXTANG, ISTAT)
C
NUMCHR = 4
XCORS(1) = 5.50
YCORS(1) = 7.0
TEXT = HI!
C
C
C
CALL SIGSCL(ISTAT)

C
C OPEN POLYGON FILE PICTURE SEGMENT
C
LGBTYP = 30
C
C DO A POLYGON COLORFILL USING LINES
C
ICOLOR = 4
CALL SIGPCL(ICOLOR, ISTAT)
IF(ISTAT .GT. 0 ) GO TO 800
C
NUMVTX = 5
XCORS(1) = 4.50
YCORS(1) = 6.50
XCORS(2) = 7.50
YCORS(2) = 6.50
XCORS(3) = 7.50
YCORS(3) = 8.0
XCORS(4) = 4.50
YCORS(4) = 8.0
XCORS(5) = 4.50
YCORS(5) = 6.50
write(6, 155)
155 format( b)
C
CALL SIGPFL(NUMVTX, XCORS, YCORS, ISTAT )
C
C
CALL SIGSCL(ISTAT)
C
C CLOSE THE SECOND PICTURE
C
CALL SIEPIC (ISTAT)
C
IF(IDBUG .EQ. 1) THEN
WRITE(LUNBUG, 2002)
END IF
2002 FORMAT(15X, ***** END OF SECOND PICTURE ***** )
C
C CLOSE THE GRAPHICS FILE
800 CALL SIEZGF
CALL SIEZIG
C
999 CONTINUE
IF(ISTAT .NE. 0) WRITE(LUNERR, 899) NAMRET, ISTAT
899 FORMAT( ****** ,A6, - ERROR, PROGRAM DID NOT COMPLETE ,
1 SUCCESSFULLY: STATUS FLAG = ,I5)
C
WRITE(LUNBUG,9993) NAMRET
9993 FORMAT(//,20X, ++++++ ENDING OF TESTING ROUTINE ++++++ ,//,
. 1X,30(=),2X,A6,2X,30(=) )
C
STOP
END

Subroutine Descriptions
The most important parts of this guide are the subroutine descriptions.
Considerable effort has gone into constructing a set of consistent
interfaces.
Major ZPI/O Groupings

The Z-MAP Plus I/O Access Library routines are separated into five
major categories:
Initialize/Terminate ZPI/O Environment (page 35)

Transfer, Convert, or List Information (page 43)
Draw and Plot Features (page 69)
Graphics Utilities (page 77)
File Utilities (page 169)
Presentation of Information
The following categories of information are included for subroutine
descriptions:
Name
Function
Note
Environment
Format
Input Arguments
Output Arguments
25 ZPI/O Overview: Subroutine Descriptions R2003.0

Name
Subroutine names are always six characters long, the first character
being an S. This is followed by one of the following:
an I, for the original version of standard ZPI/O subroutine

an O, for the original version of ZPI/O output graphics
an n, where n is a revised version number
The remaining four characters are intended to convey the purpose of

the subroutine.
Example Subroutine Names
S2ALIN is the second version of SIALIN and S3GELM is the third version of
SOGELM.
Function
This is a brief, one-line description of what the subroutine does.
Additional detail is provided in the paragraph(s) that follow.
Note
Included are notes about arguments and other subroutines, examples,
hints and suggestions.
Environment
The environment description covers the environment that must be
established before and after this subroutine is executed, such as any
files that must be opened, data from other subroutines, system
dependencies, etc.
R2003.0 ZPI/O Overview: Subroutine Descriptions 26

Format
This is the format of the FORTRAN 77 call statement with all required
arguments. Recommended names are provided for each argument.
Input Arguments
Input arguments are arranged in a table of three columns:
argument name
data type
description and default
Argument Name
The recommended names conform to FORTRAN-implicit typing
conventions for INTEGER and REAL.
Input/Output (I/O) Arguments
There are a few instances in which an argument may need to be both an input and
an output argument. This is especially true if a new file is being created by a
process. If that file already exists, a version number is added and passed back in
the same argument. This makes the version number available for use in a later
subroutine if it is needed.
The code appears at the left side of the argument name to indicate that the
argument is used for both input and output.
27 ZPI/O Overview: Subroutine Descriptions R2003.0

Data Type
Data types are listed as:
C = CHARACTER
D = DOUBLE PRECISION
I = INTEGER
L = LOGICAL
R = REAL
CHARACTER arguments are denoted C*kk where kk is the number of

characters required.
REAL or INTEGER arguments occupy single locations unless

explicitly noted otherwise with array, of length kk where kk is the
number of locations which should be reserved in the calling program.
CHARACTER, LOGICAL, and DOUBLE PRECISION arguments

require TYPE statements in the calling program.
Description
The description column contains a brief explanation of the arguments
function. Some arguments must have specific values. These values are
tabulated and explained in a list below the argument description. The
following mathematical symbols precede the values as needed:
> = less than

< = greater than
The notation Default = indicates computed default values.
The notation Range Options: indicates the acceptable range of values.
The notation Recommend: indicates a recommended value.
Output Arguments
Output arguments are typically used to convey completion status
information. The format of this information is essentially the same as
for Input Arguments (see pages 27 to 28).
R2003.0 ZPI/O Overview: Subroutine Descriptions 28

Comments and Suggestions
Internal Routines
There are some ZPI/O routines for which there is no documentation.
These routines are used internally by other ZPI/O routines and are, in
general, not used by application programmers.
Initializing Input Arguments

For good housekeeping, all input arguments should be initialized, since
not all machines set variables to zero or blanks. ZPI/O input checking is
based on a variable value being either zero or a selection number and a
file being either blank (if it is unused), or with a name in the argument
in order to open the file.
Calling Arguments
It is a good idea to use only variable names rather than constants in the
calling arguments, because on occasion that variable may be
overwritten due to a conflict in parameters. If this is found to be the
case, please notify us. Also, the variables should not be set using the
PARAMETER statement since these cannot be overridden.
Using the Debug Option, IDBUG

If you are having problems running one of the ZPI/O subroutines, use
the debug argument, IDBUG, to assist you in determining what the
input and output arguments are and in which subroutine call the
problem is occurring. IDBUG is initialized to a user value in SICOMM
or SIISIL and reset using the subroutine S2DBUG.
If IDBUG = 1, printing of debug statements is turned on. If IDBUG =

0, printing of debug statements is turned off.
If you see a string of asterisks (****) in a printing of the input/output

debug arguments, verify your values. The asterisks indicate a value is
outside the range of the print format. If the printout of asterisks persists,
contact the Landmark Customer Support staff.
29 ZPI/O Overview: Comments and Suggestions R2003.0

If you are still having problems, attempt the same process in

Z-MAP Plus and see what the results are. Especially, check if the files,
master files and graphics files are good.
Using the Status Flag Option, ISTAT

All errors should be printed by ZPI/O code. The application
programmer should check the code and decide what to do, but need not
write a message.
ISTAT <0 Warning message and some action has been taken to
continue processing
ISTAT = 0 Operation was successful
ISTAT >0 Fatal error occurred, application programmer should

close down subsystems, pictures, files, etc., for a clean
abend. Output arguments are printed but they may not
represent good values, depending on where the error
occurred.
Opening and Closing Files

For the Draw and Plot routines, the files must be closed.
Files should be opened when working with most of the File utilities.
Graphics files and pictures usually must be opened before Graphics

utilities can be performed.
If files or pictures are opened, they should be closed before terminating

the application program.
Every effort is made to close all files within a ZPI/O subroutine, but
sometimes some internal files may be left open. If you have trouble of
this kind, perform the following loop after the call in question. This
guarantees that the files are closed:
CALL SIname (
DO xxx, I = 1,5
CALL SIFCLO(I, ISTAT)
xxx CONTINUE
R2003.0 ZPI/O Overview: Comments and Suggestions 30

Master File Numbers

There are two methods for specifying master file numbers:
1. If you are specifying an old file:

0 = Search all master files for this file
N = Search the specified master file for this file
2. If you are specifying a new file:

0 = Output the file on the scratch master file
N = Output the file on the specified master file
Reading Sequential Data

To read sequential data, use the routine SIFRED:
CALL SIFRED (LOGFIL, IREC, NWRDS, DATA, ISTAT)
IREC has a special property. If a number of sequential reads are to be

performed after positioning the file, do the following series of steps:
1. Set IREC = N, where N is the first record to be read.
2. Call this routine SIFRED.
3. Set IREC = 0 for the remaining number of sequential reads.
Writing Sequential Data

To write sequential data, use the routine SIFWRT:
CALL SIFWRT (LOGFIL, IREC, NWRDS, DATA, IWORD,

ISTAT)
IREC has a special property. If a number of sequential writes are to be

performed after positioning the file, do the following series of steps:
1. Set IREC = N, where N is the first record to be written.
2. Call this routine SIFWRT.
3. Set IREC = 0 for the remaining number of sequential writes.

Reading a File
1. Open the old file SIOOPN.
2. Read the parameter record SIPRRD, SIPRRG or SIPRRC.
3. If the file is a data file, read the field descriptors SIFLDR. The
number of field descriptors is obtained from the argument call.
4. Read the records SIFRED.
Using IWORD To Read Sequential Records
Do not use the number of records or columns as a means of knowing when

you have finished reading the file. Instead, use the argument IWORD
number of sequential words remaining to read. It is zero if all the records
have been read.
5. Close the file SIFCLO.
Creating a File
1. Open the new file SINOPN.
2. If the file is a data file, write the field descriptors SIFLDW.

Write one field descriptor for each field to be written on the file.
3. Write the records SIFWRT.
4. Write the parameter record SIPRWD, SIPRWG or SIPRWC.
5. Close the file SIFCLO.
6. Check the file and fields SIGRST, SICTST or SIFDST.
7. List the file SILIST/SIGLST.
For additional information, see Creating a Member File on page 241.

Naming Output Data Files

Any file which is created in a ZPI/O run (usually referred to as an
output file in the ZPI/O documentation) should be a variable argument.
If a routine creates a new member file and you specify a name that
already exists, a version number is added to this filename.
This new filename (with the added version number) is returned to you
in the same argument you sent. It is very important to set the name of
the file equal to a parameter, send that parameter as part of the calling
argument.
For example, S4CDTR argument NAMODA for the name of the output
data file should be coded as:
CHARACTER *24 NAMODA

NAMODA = OUTPUT FILE
CALL S4CDTR(...
If the name exists, it is returned in the argument as:
NAMODA = OUTPUT FILE V-01
ISTAT is set to 1 and a warning message is sent:
****** WARNING - DUPLICATE FILES, A VERSION NUMBER HAS BEEN

ADDED
This notifies you that you have the correct filename, if you use the
name in another routine after S4CDTR.
Input/Output Arguments in the Subroutine Descriptions
For files of this type, the documentation shows the code up on the left side of
the page to indicate that it is both an input and an output argument.

Reading and Writing Grids

Grids are stored in a columns so that an NROW by NCOL size grid
occupies NROW*NCOL words in a member file. The grid element
(IROW,ICOL) is the (ICOL 1)*NROW + IROW word on the grid
member file.
For example, the grid cell denoted by the XX in the diagram below is
cell (10,10). It is the (10 1)*12 + 10 = 118th word sequentially on the
member grid file.
XMAX
XMIN
Columns
1 2 3 4 5 6 7 8 9 10 11 12 YMAX
YMAX
1
2
3
4
5
Rows
6
7
8
9
10 XX
11
12
YMIN YMIN
XMIN
XMAX
For additional information, see Reading and Writing Grids on

page 246.

Initialize/Terminate ZPI/O Environment
Introduction
Use the Initialize/Terminate ZPI/0 Environment subroutines for these

tasks:
Initialize or terminate the ZPI/O environment.
Initialize the system-wide common blocks.
Set where the messages from various parts of the Landmark
subsystems are output.
Reset the debug print option.
R2003.0 Initialize/Terminate ZPI/O Environment: Introduction 35

Internal Routines
Some library routines are not included in the documentation. These

routines are used internally by other library routines and are typically
not used by application programmers. The internal routines for
Initialize/Terminate ZPI/O Environment are:
SIEROP Print the error messages for opening files by routines

ZINOPN and ZIOOPN
SIERVN Report that a shell (obsolete) routine has an error from a

called new version routine
SIMSGW Print special type of message looping for arrays in

debug statements
SISSIL Start up system-wide common blocks
36 Initialize/Terminate ZPI/O Environment: Internal Routines R2003.0

Initialization and Termination Routines
S2DBUG
Function Reset the debug print flag
Environment The input argument IDBUG is set initially by SICOMM or SIISIL,

when initializing the ZPI/O environment. After that routine is called,
you can reset the debug print flag by calling this routine.
Format CALL S2DBUG ( IDBUG , ISTAT )
Input Arguments
Argument Data Description
Name Type and Default
IDBUG I Whether to print debug statements:
0 = Off, do not print debug statements
1 = On, print the debug statements
Output Arguments
ISTAT I Status flag:
0 = Operation was successful
1 = Error, debug print file cannot be opened.
IDBUG reset to zero
R2003.0 Initialize/Terminate ZPI/O Environment: Internal Routines S2DBUG 37

SICOMM
Function Initialize the ZPI/O environment
This subroutine initializes system-wide common blocks and must be

the first subroutine called when using the Z-MAP Plus I/O Access
Library (ZPI/O). This routine sets all output print units to the standard
default, usually unit 6.
For more control on where messages are printed, see SIISIL (page 41).
Environment The application program must contain the declaration:

COMMON/WRKSPC/IWORK(N)
where N is normally greater than 10,000. A typical value for N is

100,000. However, N must be equal to LTHWRK.
Call this routine (or SIISIL) first and only once in all application
programs.
Format CALL SICOMM ( IDBUG , LTHWRK )
Input Arguments
1 = On, print debug statements
LTHWRK I Length of the workspace. It must be at least 3.
See Environment above.
Output Arguments None
38 Initialize/Terminate ZPI/O Environment: Internal Routines SICOMM R2003.0

SIESIL
Function Terminate the ZPI/O environment
Environment This subroutine should be called after all ZPI/O processing has been
completed and if an abend condition occurs. SIISIL or SICOMM must
have been called to initialize the ZPI/O environment.
Format CALL SIESIL ( ISTAT )
Input Arguments None
Output Arguments
1 = Error, problem closing the files
R2003.0 Initialize/Terminate ZPI/O Environment: Internal Routines SIESIL 39

SIEZIM
Function Close a ZIMS file
This subroutine removes lock files on Unix systems. You can call it on
other systems, but it is unnecessary.
Environment Call this routine during the exit process for any programs that use
master files (MFDs). Call so that normal exits and any error exits both
call this routine.
Format CALL SIEZIM
40 Initialize/Terminate ZPI/O Environment: Internal Routines SIEZIM R2003.0

SIISIL
Function Initialize the ZPI/O environment with output file control
This subroutine initializes the ZPI/O environment, the system-wide

common blocks, the message utility and some of the logical units.
SIISIL or SICOMM must be the first subroutine called when using the
Z-MAP Plus I/O Access Library.
Notes If there is any problem opening the files, a STOP may occur with the
message:
' ****** SISSIL - ERROR, PROBLEM OPENING FILES '
For Unix users the ZPI/O application needs to explicitly open those
output units (LUNINF, LUNSTA, LUNWAR, LUNERO, LUNBUG)
if IPROC = 1.

COMMON/WRKSPC/IWORK(N)
where N is normally greater than 10,000. A typical value for N is

100,000. However, N must be equal to LTHWRK.
Call this routine (or SICOMM) first and only once in all application
programs.
Format CALL SIISIL (

1 IDBUG , LTHWRK , LUNINF , LUNSTA , LUNWAR ,
2 LUNERO, LUNBUG , LUNDM1 , LUNDM2 , IPROC ,
3 ISTAT )
Input Arguments
1 = On, print debug statements
LTHWRK I Length of the work space. It must be at least 3.
See Environment above.
LUNINF I Logical unit number for output informative
messages.
Default = 6
Range Options: 099
LUNSTA I Logical unit number for output statistical (report)
messages.
Default = 6
Range Options: 099
R2003.0 Initialize/Terminate ZPI/O Environment: Internal Routines SIISIL 41


LUNWAR I Logical unit number for output warning
messages.
Default = 6
Range Options: 099
LUNERO I Logical unit number for output error messages.
Default = 6
Range Options: 099
LUNBUG I Logical unit number for output ZPI/O input and
output debug messages.
Default = 6
Range Options: 099
LUNDM1 I Currently not used.
LUNDM2 I Currently not used.
IPROC I Where messages are to be presented:
0 = Output all messages to screen
1 = Output messages to designated files
Output Arguments
1 = Warning, invalid informative unit,
process, or debug flag. The value has
been reset
1 = Error, invalid licensing setup
2 = Error, option unavailable
42 Initialize/Terminate ZPI/O Environment R2003.0

Transfer, Convert, or List Information
Introduction
Use the Transfer, Convert, or List Information subroutines for these

tasks:
Convert data from one format to another format.
Generate lists and reports for various types of files.
Compute statistics for data and grid files.
Transfer data from a disk file to a member file and vice versa.
Internal Routines

not used by application programmers. The internal routines for
Transfer, Convert or List Information are:
SICDPM Verify the input arguments for coordinate transformation

from x,y to latitude/longitude
SILFMT Store the column header
SILWRT Print selected data fields by the format in the character

string FRMT
43 Transfer, Convert, or List Information: Introduction R2003.0

Routines to Transfer, Convert, or List Information
S2FLIN
Function Transfer information from an external file into a member of a master

file
This subroutine transfers an external file into a member file. The user
must describe the input file by means of a format, either on the input
file or in a format file. For information and examples of how to do this,
see Appendix D. Import/Export in the Z-MAP Plus Reference
Manual. (Where the term format is used in this subroutine description,
the term format group is used in Appendix D. Import/Export.)
Environment The ZPI/O and ZIMS environments must be initialized before you call
this routine.
Format CALL S2FLIN (

1 NAMDAT , NAMDIC , NAMGRP , NAMFIL , LATTNM ,
2 GRPCHR , CMTCHR , HSTCHR , DICFLG , MFDNUM ,
3 LOGDIC , LOGDAT , ISTAT )
Input Arguments
NAMDAT C*80 Name of the external input data file.
NAMDIC C*80 Name of format file containing the format.
Blanked if format is on the input data file.
NAMGRP C*40 Name of format in NAMDIC file which describes
the input data file.
NAMFIL C*24 Name of output member file to create.
LATTNM C*24 Name of the RESIN lattice which specifies the
geometry of the cell table being imported.
Required if importing a RESIN cell table file,
blanked otherwise.
GRPCHR C*1 Format identifier.
Default = @
CMTCHR C*1 Comment record identifier.
Default = !
HSTCHR C*1 History record identifier.
Default = +
DICFLG L Whether the format and input data are on the
same file:
.TRUE. = They are on the same file
.FALSE. = They are on different files
44 Transfer, Convert, or List Information: Internal Routines S2FLIN R2003.0


MFDNUM I Number of master file to contain the member data
file.
Range Options: 05
LOGDIC I Logical unit number for the format file.
Default = 61, if DICFLG = .FALSE.
62, if DICFLG = .TRUE.
Range Options: 099
LOGDAT I Logical unit number for the input formatted data
file.
Default = 62
Range Options: 099
Output Arguments
2 = Warning, input file is empty
1 = Warning, format file supplied, but
DICFLG = .TRUE.; reset to use this input
data file
1 = Error, problem importing data file
2 = Error, file containing the format and
import data file are the same, but
DICFLG indicates they are different
R2003.0 Transfer, Convert, or List Information: Internal Routines S2FLIN 45

S2GRST
Function Compute grid file statistics
This subroutine obtains statistics about all or part of a grid file.
Environment The ZPI/O and ZIMS environments must be initialized before this
routine is called.
Format CALL S2GRST (

1 NAMGRD , MFDGRD , IHISGR , MNRWIN, MXRWIN ,
2 MNCWIN , MXCWIN , NROWS , NCOLS , NZVAL ,
3 NZNON , XMIN , XMAX , YMIN , YMAX ,
4 GXINC , GYINC , ZMIN , ZMAX , ZRANGE ,
5 ZMEAN , ZRMS , ZSTD , ZRELVA , ZRMSCR ,
6 XBAND , YBAND , REACH , ZNON , ISTAT )
Input Arguments
NAMGRD C*24 Name of the input grid file.
MFDGRD I Number of the master file containing the input
grid file.
Range Options: 05
IHISGR I History display for input grid file:
0 = Do not display history information
1 = Display history information
MNRWIN I Minimum row at which to begin statistics (top
edge of window). A zero uses the default.
Default = 1
MXRWIN I Maximum row at which to end statistics (bottom
Default = Number of rows
MNCWIN I Minimum column at which to begin statistics
(left edge of window). A zero uses the default.
Default = 1
MXCWIN I Maximum column at which to end statistics (right
Default = Number of columns
46 Transfer, Convert, or List Information: Internal Routines S2GRST R2003.0

Output Arguments
NROWS I Number of rows.
NCOLS I Number of columns.
NZVAL I Number of z value nodes.
NZNON I Number of null data nodes (ZNONs).
XMIN R Minimum x coordinate.
XMAX R Maximum x coordinate.
YMIN R Minimum y coordinate.
YMAX R Maximum y coordinate.
GXINC R The x direction gridding interval.
GYINC R The y direction gridding interval.
ZMIN R Minimum surface value.
ZMAX R Maximum surface value.
ZRANGE R Surface range.
ZMEAN R Mean of z.
ZRMS R Root mean square of z.
ZSTD R Standard deviation of z.
ZRELVA R Relative variation of z.
ZRMSCR R Root mean square curvature of z.
XBAND R The x direction collection radius.
YBAND R The y direction collection radius.
REACH R Data collection radius.
ZNON R Null data value (ZNON).
R2003.0 Transfer, Convert, or List Information: Internal Routines S2GRST 47



1 = Error, invalid master file number or
master file is read-only
2 = Error, duplicate files, specify master file
number
3 = Error, cannot find the file
4 = Error, 5 files already in use
5 = Error, reading parameter record
6 = Error, invalid grid increments
48 Transfer, Convert, or List Information: Internal Routines S2GRST R2003.0

S4CDTR
Function Convert from x,y to latitude/longitude and vice versa
This subroutine converts x,y coordinates to longitude and latitude

coordinates or the inverse relationship, using a member file.
routine is called.
Format CALL S4CDTR (

1 NAMIDA , NAMODA , NAMFDA , NAMFDB , MFDIDA ,
2 MFDODA , IHSIDA , IDIREC , IFLDA , IFLDB ,
3 IHEM , IPJCOD , ISPCOD , IUNCOD , IUTMCD ,
4 IUTMOP , IDTLN , IRADTY , UNTFAC , BOTPAR ,
5 TOPPAR , REFLAT , SFLAT , REFLON , SFLON ,
6 FNORTH , FEAST , AXISA , AXISB , AZMTH ,
7 SCALE , ZNONOT , ISTAT )
Input Arguments
NAMIDA C*24 Name of input data file.
NAMODA C*24 Name of output data file.
NAMFDA C*20 Name of output Y (Northing) or Latitude field. If

blank, defaults to name for given field type.
NAMFDB C*20 Name of output X (Easting) or Longitude field. If

blank, defaults to name for given field type.
MFDIDA I Number of the master file containing the input

data file.
Range Options: 05
MFDODA I Number of the master file to contain the output

data file.
Range Options: 05
IHSIDA I History display for input data file:

IDIREC I Direction of the transformation:

1 = Forward (LAT,LONG to X,Y)
2 = Inverse (X,Y to LAT,LONG)
R2003.0 Transfer, Convert, or List Information: Internal Routines S4CDTR 49


IFLDA I Field number of the Y (Northing) or Latitude

field in input data file. A zero finds and uses the
first field of the appropriate type.
IFLDB I Field number of the X (Easting) or Longitude

field in input data file. A zero finds and uses the
first field of the appropriate type.
IHEM * I Which hemisphere. Needed only if IPJCOD = 1:

1 = Northern
2 = Southern
50 Transfer, Convert, or List Information: Internal Routines S4CDTR R2003.0


IPJCOD * I Cartographic projection code:

17 = Grads and Van Der Grinten I
16 = Grads and Bipolar Oblique Conic
Conformal
15 = Grads and Cassini-Soldner
14 = Grads and New Zealand Map Grid
13 = Grads and Oblique Transverse Mercator
12 = Grads and American Polyconic
11 = Currently not used
10 = Grads and Albers Equal Area
(equivalent) with two standard parallels
9 = Grads and Modified Rectangular
Orthotomic Polyconic
8 = Grads and Azimuthal Orthographic
7 = Grads and Azimuthal Stereographic
6 = Grads and Azimuthal Gnomonic
5 = Grads and Conformal Lambert with two
standard parallels
4 = Grads and Conformal Lambert with one
standard parallel
3 = Grads and Standard Mercator
2 = Grads and General Transverse Mercator
1 = Degrees and Universal Transverse
Mercator
2 = Degrees and General Transverse
Mercator
3 = Degrees and Standard Mercator
4 = Degrees and Conformal Lambert with
one standard parallel
5 = Degrees and Conformal Lambert with
two standard parallels
6 = Degrees and Azimuthal Gnomonic
7 = Degrees and Azimuthal Stereographic
8 = Degrees and Azimuthal Orthographic
9 = Degrees and Modified Rectangular
Orthotomic (Polyconic)
10 = Degrees and Albers Equal Area
equivalent with two standard parallels
12 = Degrees and American Polyconic
13 = Degrees and Oblique Mercator
14 = Degrees and New Zealand Map Grid
15 = Degrees and Cassini-Soldner
16 = Degrees and Bipolar Oblique Conic
Conformal
17 = Degrees and Van Der Grinten I


ISPCOD * I Reference spheroid for projection:

1 = User defined
2 = Everest 1830
3 = Malayan Everest 1830
4 = Bessel 1841
5 = Airy 1858
6 = Clarke 1858
7 = Clarke 1866
8 = Clarke 1880
9 = Hayford 1909
10 = Krassovsky 1940
11 = Hough 1956
12 = Fischer 1960 (Mercury)
13 = Kaula 1961
14 = I.U.G.G. 1967 (Australian National 1967/
South American 1969)
15 = Fischer 1968 (Mercator modified)
16 = WGS-72 1972
17 = I.U.G.G. 1975
18 = Helmert
19 = Ghana National
20 = WGS-84 (GRS-80)
IUNCOD * I Units for projected coordinates:

1 = User defined
2 = Meters
3 = Feet
4 = Yards
5 = Inches
6 = Kilometers
7 = Nautical miles
8 = Statute miles
9 = U S Survey feet
IUTMCD * I UTM zone number. Used if IPJCOD = 1.

(See Appendix G. Mapping and Cartographic
Projections in the Z-MAP Plus Reference
Manual.)
IUTMOP I Method for specifying projection, if IPJCOD = 1:

1 = UTM zone number
2 = Central meridian reference longitude
IDTLN I Mapping across the dateline:

0 = Not mapping across the dateline
1 = Mapping across the dateline
Note: Set this to zero for grads.


IRADTY * I Type of calculation to use to convert spheroid

dimensions A & B to radius:
1 = Equatorial
2 = Equal Surface Area
3 = Equal Volume
4 = Gaussian
UNTFAC * R Projected coordinates units factor. Needed only

if IUNCOD = 1.
BOTPAR * R Standard parallel closest to the equator (least), in

degrees.
TOPPAR * R Standard parallel closest to pole (greatest), in

degrees.
REFLAT * R Reference latitude.
SFLAT * R Scale factor along reference latitude.
REFLON * R Reference longitude.
SFLON * R Scale factor along reference longitude.
FNORTH * R False northing.
FEAST * R False easting.
AXISA * R Semimajor axis, if spheroid is user-defined

(ISPCOD = 1).
AXISB * R Semiminor axis, if spheroid is user-defined

(ISPCOD = 1).
AZMTH * R Azimuth of central line at skew origin.
SCALE * R Scale factor at origin.
ZNONOT R Output field null data value (ZNON).

Output Arguments
2 = Warning, problem writing out extended
history
1 = Warning, duplicate files, a version
number has been added
1 = Error, duplicate files, invalid master file
number or master file is read-only
2 = Error, invalid version number
number
7 = Error, reading field descriptors
8 = Error, writing field descriptors
9 = Error, writing parameter record
10 = Error, defining default field descriptor
11 = Error, setting up coordinate
transformation parameters
12 = Error, converting parameters
13 = Error, invalid field matchups
14 = Error, performing the coordinate
transformation
15 = Error, writing projection information to
adjunct record
16 = Error, file does not contain the necessary
fields
17 = Error, UTM is not valid for grads map

Table 1: Checklist for Projection Arguments vs. Projection Type

Projection Type
Bipolar Oblique Conic Conformal
Universal Transverse Mercator

Oblique Transverse Mercator
General Transverse Mercator
Azimuthal Stereographic
Double Parallel Lambert

Azimuthal Orthographic
New Zealand Map Grid
Single Parallel Lambert

Azimuthal Gnomonic
American Polyconic
Modified Polyconic
Albers Equal Area
Standard Mercator
Van Der Grinten I

Cassini-Soldner
Arguments
Name Description
AXISA Semimajor Radius A if ISPCOD = 1* O N O O O N O O O O N O O O O O
AXISB Semiminor Radius B if ISPCOD = 1* O N O O O N O O O O N O O O O O
AZMTH Azimuth of center line at skew origin N N N N N N N N N N N Y N N N N
1
BOTPAR Least Standard Parallel Y N N N N N N Y N N N N Y N N N
FEAST False Easting O O O O O O N O O O O O O O N O
FNORTH False Northing O O O O O O O O O O N O O O O O
IHEM Hemisphere N N N N N N N N N N N N N N O N
IPJCOD Projection Code Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
ISPCOD Spheroid Code Y Y Y Y N N Y Y Y Y N Y Y Y Y Y
IUNCOD Units Code Y Y Y Y Y Y Y Y Y Y N Y Y Y N Y
IUTMCD UTM Zone N N N N N N N N N N N N N N O4 N
IRADTY Radius Calculation Method N N N N N N N N N N N N N N N Y
REFLAT Reference Latitude Y1 Y Y Y Y N Y Y Y Y1 N Y Y N N N
REFLON Reference Longitude Y2 Y Y Y Y N Y Y Y Y2 N Y Y Y O3 Y
SCALE Scale factor at origin N N N N N N N N N N N Y N N N N
SFLAT Latitude Scale Factor N N N N N N N N N Y N N N N N N
SFLON Longitude Scale Factor N N N N N N N N Y Y2 N N N N N N
TOPPAR Greatest Standard Parallel Y N N N N N N Y N N N N N N N N
UNTFAC Unit Factor if IUNCOD = 1* O O O O O O O O O O N O O O N O
Key:
Y = argument required 1 Also serves as a single standard parallel
2
N = argument not required Polyconic projection also has a central meridian with associated scale factor
3
O = argument optional. If not Hemisphere defines false northing for UTM
specified, default value is used 4 One or the other is required
* User defined

SICTST
Function Compute control point file statistics
This subroutine obtains statistics about a control point file, which must
contain an X (Easting) field and a Y (Northing) field.
routine is called.
Format CALL SICTST (

1 NAMDAF , MFDNDA , IHISDA , IZFLOC , NCPRED ,
2 NCPWIN , NOZNON , XFIRST , YFIRST , ZFIRST ,
3 XLAST , YLAST , ZLAST , XMIN , XMAX ,
4 XRANGE , YMIN , YMAX , YRANGE, ZMIN ,
5 ZMAX , ZRANGE , ZMEAN , ZRMS , ZSTD ,
6 ZNON , ISTAT )
Input Arguments
NAMDAF C*24 Name of the input control point file. It must

contain an X (Easting) field and a Y (Northing)
field.
MFDNDA I Number of the master file containing the input

data file.
Range Options: 05
IHISDA I History display for the input data file:

IZFLOC I Field number of the non-text field in the control

point file on which to obtain statistics, referred to
as z statistics. A zero finds and uses the first field
of the appropriate type.
Recommend: 3
56 Transfer, Convert, or List Information: Internal Routines SICTST R2003.0

Output Arguments
NCPRED I Number of points read.
NCPWIN I Number of points in the window.
NOZNON I Number of null data values (ZNONs).
XFIRST R First x coordinate.
YFIRST R First y coordinate.
ZFIRST R First z coordinate.
XLAST R Last x coordinate.
YLAST R Last y coordinate.
ZLAST R Last z coordinate.
XMIN R Minimum x value.
XMAX R Maximum x value.
XRANGE R Range of x.
YMIN R Minimum y value.
YMAX R Maximum y value.
YRANGE R Range of y.
ZMIN R Minimum z value.
ZMAX R Maximum z value.
ZRANGE R Range of z.
ZMEAN R Mean of z.
ZRMS R Root mean square of z.
ZSTD R Standard deviation of z.
ZNON R Null data value.
R2003.0 Transfer, Convert, or List Information: Internal Routines SICTST 57



number
7 = Error, processing field descriptors
missing x,y and/or z fields
8 = Error, field chosen is character field
58 Transfer, Convert, or List Information: Internal Routines SICTST R2003.0

SIFDST
Function Compute statistics for a field

This subroutine computes statistics for a non-character field. Field
statistics for grid files and other special file types (file type greater than
12) cannot be computed. See Appendix B. File and Field Codes in
the Z-MAP Plus Reference Manual.
Statistics are available for a grid file by using the grid statistics routine
S2GRST.
routine is called.
Format CALL SIFDST (
1 NAMDAT , TYPRPT , ALLWIN , MFDDAT , IHSDAT ,
2 IFDINX , WINMIN , WINMAX , NCPRED , NCPWIN ,
3 NOZNON , FDFRST , FDLAST , FDMIN , F DMAX ,
4 FDRANG , FDMEAN , FDRMS , FDSTD , FDREL ,
5 ZNON , ISTAT )
Input Arguments
NAMDAT C*24 Name of the input data file.
TYPRPT C*8 Type of report printed:
NONE = No report
PARTIAL = Summary report
FULL = Full report
ALLWIN C*6 Type of data windowing. Blanked if the default
is to be used.
ALL = Examine all the field values.
Window limits are set to 1.0E30
and 1.0E30.
WINDOW = Examine field values in window.
MFDDAT I Number of the master file containing the input

data file.
IHSDAT I History display for data file:
IFDINX I Field number of the field in the file for which
statistics are to be computed. A zero finds and
uses the first z value.
WINMIN R Minimum allowed value. Values less than this
bound are not used in the computation of the
statistics. Required only if ALLWIN =
WINDOW.
R2003.0 Transfer, Convert, or List Information: Internal Routines SIFDST 59


WINMAX R Maximum allowed value. Values greater than
this bound are not used in the computation of the
statistics. Required only if ALLWIN =
WINDOW.
Output Arguments
NCPRED I Number of points read.
NCPWIN I Number of points in the window.
NOZNON I Number of null data values (ZNONs) on the file.
FDFRST R First coordinate in the window.
FDLAST R Last coordinate in the window.
FDMIN R Minimum value used in the computation.
FDMAX R Maximum value used in the computation.
FDRANG R Range of values in the window.
FDMEAN R Mean of values in the window.
FDRMS R Root mean square of values in the window.
FDSTD R Standard deviation of values in the window.
FDREL R Relative variation of values in the window.
ZNON R Null value.
number
5 = Error, statistics cannot be obtained for this
file type
8 = Error, field selected is a character field
9 = Error, invalid report type
10 = Error, invalid field index
11 = Error, problem computing field statistics
60 Transfer, Convert, or List Information: Internal Routines SIFDST R2003.0

SIFLOT
Function Transfer information from a member of a master file to an external file
This subroutine transfers a member of a master file to an external data

file, using the field and parameter descriptions on the member file or
by means of a format file. For examples of format file descriptions, see
Appendix D. Import/Export in the Z-MAP Plus Reference Manual.
(Where the term format is used in this subroutine description, the term
format group is used in Appendix D. Import/Export.)
routine is called.
Format CALL SIFLOT (

1 NAMDAT , NAMDIC , NAMGRP , NAMFIL , GRPCHR ,
2 CMTCHR , HSTCHR , DICFLG , HDRFLG , MFDNUM ,
3 IHSFIL , LOGDIC , LOGDAT , ISTAT )
Input Arguments
NAMDAT C*80 Name of external output formatted data file.
NAMDIC C*80 Name of format file containing the format.

Blanked if there is none.
NAMGRP C*40 Name of format in the NAMDIC file which

describes the output formatted data file.
NAMFIL C*24 Name of member file to be exported.
GRPCHR C*1 Format identifier.

Default = @
CMTCHR C*1 Comment record identifier.

Default = !
HSTCHR C*1 History record identifier.

Default = +
DICFLG L Whether the file containing the format is to be

used to export the data:
.TRUE. = Use the file containing the format to output
the data
.FALSE. = Use the member descriptions to output the
data
R2003.0 Transfer, Convert, or List Information: Internal Routines SIFLOT 61


HDRFLG L Whether the format descriptor group and history

information is to be output to the formatted data
file:
.TRUE. = Include format descriptor group and history
information on the formatted data file
.FALSE. = Do not include format descriptor group and
history information on the formatted data
file
MFDNUM I Number of the master file containing the member

file to be exported.
Range Options: 05
IHSFIL I History display for the member file:

LOGDIC I Logical unit number for the format file

Default = 63, if DICFLG = .TRUE.
Range Options: 099
LOGDAT I Logical unit number for the output data file.

Default = 64
Range Options: 099
Output Arguments
1 = Error, problem importing data file
2 = Error, the file format dataset and export
file have the same name
62 Transfer, Convert, or List Information: Internal Routines SIFLOT R2003.0

SIGLST
Function List a grid as a grid or contours
This subroutine prints a report of all or part of the grid, plots the
contour representation, or both.
routine is called.
Format CALL SIGLST (

1 NAMGRI , GRDFMT , MFDGRD , IHSGRD , LOGRPT ,
2 IRPTYP , NROWMN , NROWMX , NCOLMN, NCOLMX ,
3 LBRWCL , NUMCTR , NUMPOS , CTRINT , CTRMIN ,
4 ISTAT )
Input Arguments
NAMGRI C*24 Name of the input grid.
GRDFMT C*80 Output format for the grid report. Blanked if the
default format is to be used.
Default = (1X, 5(G13.7,2X))
MFDGRD I Number of the master file containing the input

grid.
Range Options: 05
IHSGRD I History display for input file:

LOGRPT I Logical unit number on which to print the report.

Range Options: 099
IRPTYP I Report type:

0 = Grid report
1 = Contour report
2 = Both reports
NROWMN I Minimum row at which to begin printing (top

edge of window).
Default = 1
NROWMX I Maximum row at which to end printing (bottom

edge of window).
Default = Number of rows
R2003.0 Transfer, Convert, or List Information: Internal Routines SIGLST 63


NCOLMN I Minimum column at which to begin printing (left

edge of window).
Default = 1
NCOLMX I Maximum column at which to end printing (right

edge of window).
Default = Number of columns
LBRWCL I Whether to label the rows and columns. Needed

only for grid report:
0 = Do not label the rows and columns
1 = Label the rows and columns
NUMCTR I Number of contours. Needed only if contour plot

requested.
Range Options: 0100
NUMPOS I Number of print positions across the top of plot.

Needed only if contour plot requested.
Default = NCOLMX NCOLMN + 1
Range Options: 1132
CTRINT R Interval between adjacent contours. Needed only

if contour plot requested.
CTRMIN R Minimum contour interval at which to begin

printing. Needed only if contour plot requested.
64 Transfer, Convert, or List Information: Internal Routines SIGLST R2003.0

Output Arguments
3 = Warning, number of contour levels is
greater than 100. It has been reset.
2 = Warning, bad input format. Default
format being used.
1 = Warning, report unit was zero. It has been
reset.
0 = Operation was successful.
master file is read-only.
number.
3 = Error, cannot find the file.
4 = Error, 5 files already in use.
5 = Error, this is a data file not a grid file.
6 = Error, problem reading parameter record.
7 = Error, problem positioning the file.
8 = Error, minimums must be less than the
maximums.
9 = Error, problem loading grid.
10 = Error, problem printing grid report.
11 = Error, the interval between adjacent
contours is zero.
65 Transfer, Convert, or List Information: Internal Routines R2003.0

SILIST
Function List a data file
This subroutine prints a report listing of a data file.
Note The format to print text strings must be in the form of nA4, where n is
the number of words. (See the IFDFMT argument description below)
Z 8D 1074 = 9 chars = 3 words = 3A4
Z-MAP #1 = 8 chars = 2 words = 2A4
ZPIO LISTING = 12 chars = 3 words = 3A4
routine is called.
Format CALL SILIST (

1 NAMIDA , RPTITL , LINARA , ICLHDR , IFDFMT ,
2 MFDIDA , IHISDA , LOGRPT , NUMLIN , LSTTYP ,
3 ISTART , IEND , NUMFLD , ICLWID , IFDINX ,
4 IWDINX , WIDMIN , WIDMAX , ISTAT )
Input Arguments
NAMIDA C*24 Name of the input data file.
RPTITL C*80 Title for the report.
LINARA C*40 Line or area name.
ICLHDR C*20 Array, of length 10, containing the column

headings for the fields that are to be printed.
Blanked if default column headings are to be
used.
IFDFMT C*20 Array, of length 10, containing the format

specifications for the fields that are to printed.
Blanked if default print formats are to be used.
Note: Character strings have the format of nA4,
where n is number of words. See the note.
MFDIDA I Number of the master file containing the input

data file.
Range Options: 05
IHISDA I History display for the input data file:

R2003.0 Transfer, Convert, or List Information: Internal Routines 66


LOGRPT I Logical unit number on which to print the report.

Range Options: 099
NUMLIN I Number of lines per page. If NUMLIN is zero,

the number of lines per page is 52.
LSTTYP I Type of listing:

0 = Automatic listing
1 = Full listing
2 = Line name
3 = Area name
4 = Window listing
5 = Exception listing
Note: Automatic listing lists first 10 fields on the
data file using the standard formats.
ISTART I Record number at which to start printing. If

ISTART is zero, it is set to 1.
IEND I Record number at which to end printing. If IEND

is zero, it is set to the number of points on the file.
NUMFLD I Number of fields to print. If NUMFLD is zero, all

fields are printed.
ICLWID I Array, of length 10, containing the widths of the

columns.
IFDINX I Array, of length 10, containing the field numbers

of the fields to print.
IWDINX I Array, of length 10, containing the field numbers

of the fields used for windowing.
WIDMIN R Array, of length 10, containing the minimum

window values for the fields to print.
WIDMAX R Array, of length 10, containing the maximum

window values for the fields to print.
67 Transfer, Convert, or List Information: Internal Routines R2003.0

Output Arguments
2 = Warning, number of fields on the file was
greater than 10. Reset to 10.
1 = Warning, printer unit was zero. It has
been reset.
number.
5 = Error, this is a grid file, not a data file.
6 = Error, problem reading parameter record.
7 = Error, problem reading field descriptor.
8 = Error, no area or line name field on file.
9 = Error, problem positioning the file.
10 = Error, there is no match for line or area
name.
11 = Error, problem creating field format.
12 = Error, problem setting up column headers.
R2003.0 Transfer, Convert, or List Information: Internal Routines 68

Draw and Plot Features
Introduction
Use the Draw and Plot Features subroutines for these tasks:
draw lines from an array or member file
display and plot a picture
Internal Routines
This section describes the following internal routines for drawing and
plotting features:
S2ALIN (page 70)
S2DSPT (page 72)
S3ZLIN (page 74)
R2003.0 Draw and Plot Features: Internal Routines 69

Draw and Plot Routines
S2ALIN
Function Draw lines using array inputs

This subroutine draws lines or curves by connecting pairs of x,y
coordinates input as arrays.
Dashed lines may use up to three different dash and gap lengths to
define a dashed line pattern. For instance, a double dash patterned line
may be used to create a dash-dot pattern. Similarly, a triple dash
patterned line may be used to create a dash-dot-dot pattern.
Environment The ZPI/O and ZIGS environments must be initialized and a graphics
file and a picture opened before this routine is called.
Format CALL S2ALIN (

1 KOORD , IFSYMB , LINTYP , NUMPTS, ISYMBL ,
2 DASHLN , GAPLEN , HAPART , HSHLEN , HSHWAY ,
3 BWIDTH , SYMSIZ , XCOORD , YCOORD, CODES ,
4 ISTAT )
Input Arguments
KOORD I Coordinate system for the vertices:
0 = Vertices are in engineering units
1 = Vertices are in plotter units (in or cm).
They will not be clipped.
IFSYMB I Whether to post symbols at vertices:
0 = Do not post symbols
1 = Post symbols
LINTYP I Type of line to draw:
1 = Normal line
2 = Single dash patterned line
3 = Bold line
4 = Normal line with hachure
5 = Bold line with hachure
6 = Double dash patterned line
7 = Triple dash patterned line
NUMPTS I Number of points in arrays XCOORD,
YCOORD, and CODES.
ISYMBL I Symbol code of symbol to draw at vertices:
0 = Draw no symbols at the vertices, or
symbol codes are in array CODES
>0 = Symbol code of symbol to draw at all
vertices. (See Appendix C. Symbols,
Fonts, and Line Patterns in the
Z-MAP Plus Reference Manual.)
70 Draw and Plot Features: Internal Routines S2ALIN R2003.0


DASHLN R Array, of length 3, containing the lengths of the
solid parts of the dash pattern, in plotter units (in
or cm):
DASHLN(1) = Length of first dash
DASHLN(2) = Length of second dash
DASHLN(3) = Length of third dash
GAPLEN R Array, of length 3, containing the lengths of the

gapped parts of the dash pattern, in plotter units
(in or cm):
GAPLEN(1) = Length of first gap
GAPLEN(2) = Length of second gap
GAPLEN(3) = Length of third gap
HAPART R Length of the space between hachures, in plotter

units (in or cm).
HSHLEN R Length of the hachure marks, in plotter units (in
or cm).
HSHWAY R Direction of the hachure marks:
1 = Pointing uphill
1 = Pointing downhill
BWIDTH R Width of bold lines, in plotter units (in or cm).
Range Options: 28
SYMSIZ R Symbol size, in plotter units (in or cm).
XCOORD R Array, of length NUMPTS, containing x
coordinates of the vertices.
YCOORD R Array, of length NUMPTS, containing y
coordinates of the vertices.
CODES R Array, of length NUMPTS, specifying a symbol
code at each vertex.
Output Arguments
1 = Error, unsuccessful attempt to open a
picture segment
2 = Error, problem with the number of
vertices
Note: The number of vertices must be between 2
and 5000. At least two points are needed
to define a line. 5000 is an arbitrary limit
chosen to distinguish between large, but
legitimate, input arrays and undefined
values of input argument NUMPTS.
R2003.0 Draw and Plot Features: Internal Routines S2ALIN 71

S2DSPT
Name S2DSPT
Function Display a picture or plot a hardcopy of a picture
This subroutine plots or displays a picture to a graphics terminal or

plotter as described in the Work Station Description file.
The plotter or terminal must also be assigned before this routine is

called.
Format CALL S2DSPT (

1 ZGFNAM , PICNAM , NCOPYS , LINCUT , IDEVTY ,
2 ILGBMD , IROTAT , IDUMMY , NUMLGB , LGBTYP ,
3 SCLFCT , ISTAT )
Input Arguments
ZGFNAM C*80 Name of the graphics file containing the input

picture.
PICNAM C*80 Name of the input picture.
NCOPYS I Number of copies of the picture.
LINCUT I Whether to draw a cutline:

0 = Do not draw cutline
1 = Draw cutline
IDEVTY I Workstation type, from the Work Station

Description file (WDF).
ILGBMD I Which graphics features to plot:

1 = Plot all features
1 = Plot only the features specified in
LGBTYP
2 = Plot all the features except those specified
in LGBTYP
IROTAT I Rotation flag:

0 = Rotation not allowed for display/plot
1 = Rotation allowed for display/plot
72 Draw and Plot Features: Internal Routines S2DSPT R2003.0


IDUMMY I Reserved for future use.
NUMLGB I Number of graphics feature codes in LGBTYP.

Needed only if ILGBMD is 1 or 2.
Range Options: 050
LGBTYP I Array, of length NUMLGB, containing the

graphics feature codes. (See Appendix A.
Graphics Feature Codes in the Z-MAP Plus
Reference Manual.) Needed only if ILGBMD is
1 or 2.
SCLFCT R Scaling factor.
Output Arguments
1 = Error, performing hardcopy processing
R2003.0 Draw and Plot Features: Internal Routines S2DSPT 73

S3ZLIN
Function Draw lines using a member file
This subroutine draws lines or curves by connecting pairs of x,y points.

These vertices are contained in a member data file and are then written
to the current picture.
Dashed lines may use up to three different dash and gap lengths to
define a dashed line pattern. For instance, a double dash patterned line
can be used to create a dash-dot pattern. Similarly, a triple dash
patterned line may be used to create a dash-dot-dot pattern.
Format CALL S3ZLIN (

1 NAMZIM , MFDNZM , IHISZM , KOORD , IFSYMB ,
2 LINTYP , ISYMBL , IPYCLR , DASHLN , GAPLEN ,
3 HAPART , HSHLEN , HSHWAY , BWIDTH , SYMSIZ ,
4 ISTAT )
Input Arguments
NAMZIM C*24 Name of the input data file containing the

vertices.
MFDNZM I Number of the master file containing the input

data file.
Range Options: 05
IHISZM I History display for input data file:

KOORD I Coordinate system for the vertices:

0 = Vertices are specified in engineering units
1 = Vertices are specified in plotter units (in
or cm)
IFSYMB I Whether to post symbols at vertices:

0 = Do not post symbols
1 = Post symbols
74 Draw and Plot Features: Internal Routines S3ZLIN R2003.0


LINTYP I Type of line to draw:

1 = Normal line
2 = Single dash patterned line
3 = Bold line
4 = Normal line with hachure
5 = Bold line with hachure
6 = Double dash patterned line
7 = Triple dash patterned line
ISYMBL I Symbol code of symbol to draw at vertices:

0 = Draw no symbol at the vertices
>0 = Symbol code of symbol to draw at all
vertices. See Appendix C. Symbols,
Fonts, and Line Patterns in the
Z-MAP Plus Reference Manual.
IPYCLR I Color index for lines:

1 = Use color field index on the file to draw
lines
0255= Color index to use
DASHLN R Array, of length 3, containing the lengths of the

solid parts of the dash pattern, in plotter units (in
or cm):
DASHLN(1) = Length of first dash
DASHLN(2) = Length of second dash
DASHLN(3) = Length of third dash
GAPLEN R Array, of length 3, containing the lengths of the

gapped parts of the dash pattern, in plotter units
(in or cm):
GAPLEN(1) = Length of first gap
GAPLEN(2) = Length of second gap
GAPLEN(3) = Length of third gap
HAPART R Length of the space between hachures, in plotter

units (in or cm).

or cm).

1 = Pointing uphill
R2003.0 Draw and Plot Features: Internal Routines S3ZLIN 75


BWIDTH R Width of bold lines, in plotter units (in or cm).
SYMSIZ R Symbol size, in plotter units (in or cm).
Output Arguments
1 = Error, problem drawing lines
76 Draw and Plot Features R2003.0

Graphics Utilities
Introduction
Use the Graphics Utilities subroutines for these tasks:

initialize and terminate the graphics environment
attach and detach graphics files
open and close pictures
use graphics and picture utilities
design and create pictures from basic elements
extract graphics elements
Internal Routines

not used by application programmers. The internal routines used for
graphics utilities are:
SICPCL Close out the picture copying environment by closing

files
SICPIT Initialize picture copying environment for the assemble/

overlay routine SIPCAS
R2003.0 Graphics Utilities: Introduction 77

Graphic Routines
S2GMRK
Function Draw markers

This subroutine draws marker symbols to the current height, color, and
type at an array of locations.
This routine is only used for working on graphics features: It does not
apply to the standard applications elsewhere in this guide.
file, a picture and a graphics feature must be opened before this routine
is called.
Format CALL S2GMRK (

1 NUMMRK , XCORS , YCORS , ROTATE , ISTAT )
Input Arguments
NUMMRK I Number of markers to draw.
XCORS R Array, of length NUMMRK, containing the x
coordinates of the center of the markers, in the
currently defined coordinate system.
YCORS R Array, of length NUMMRK, containing the y
coordinates of the center of the markers, in the
currently defined coordinate system.
ROTATE R Array, of length NUMMRK, containing the
angles of rotation for the markers, in degrees.
Range Options: 0.0360.0
Output Arguments
1 = Error, number of markers is zero
2 = Error, graphics feature is not open
78 Graphics Utilities: Internal Routines S2GMRK R2003.0

Graphic Routines
S2ZGIN
Name S2ZGIN
Function Transfer the contents (pictures) of a neutral file to a graphics file

This subroutine transfers all of the pictures in a neutral graphics file to
a ZGF graphics file.
Environment The ZPI/O and ZIGS environments must be initialized and the graphics
file must not exist before this routine is called.
Format CALL S2ZGIN (

1 NAMFLT , NAMZGF , LEVRPT , LUNFLT , LUNZGF ,
2 ISTAT )
Input Arguments
NAMFLT C*80 Name of neutral (disk) file.
NAMZGF C*80 Name of new graphics file. If blank, the name of
the graphics file is assumed to be the first record
in the neutral file of the form:
Col. 114 = $HT 88 NAMZGF
Col. 1580 = Name of the graphics file
LEVRPT I Type of status report:

0 = No status report
1 = Status report output to unit LUNSTA
specified by SIISIL
LUNFLT I Number of logical unit on which to open the
neutral file.
Range Options: 099
Recommend: 10
LUNZGF I Number of logical unit on which to open the
graphics file.
Range Options: 099
Recommend: 27
Output Arguments
1 = Error, opening neutral file
2 = Error, the input graphics filename is blank
and the graphics name specified in the
neutral file is blank also
R2003.0 Graphics Utilities: Internal Routines S2ZGIN 79

Graphic Routines
S2ZGOT
Function Transfer a set of pictures from a graphics file to a neutral file

This subroutine transfers the requested pictures in a ZGF graphics file
to a neutral graphics file.
Environment The ZPI/O and ZIGS environments must be initialized before this
routine is called.
Format CALL S2ZGOT (

1 NAMZGF , NAMFLT , NAMPIC , SELECT , NUMPIC ,
3 LEVRPT , LUNZGF , LUNFLT , ISTAT )
Input Arguments
NAMZGF C*80 Name of the input graphics file.
NAMFLT C*80 Name of output neutral (disk) file.
NAMPIC C*80 Array, of length NUMPIC, containing the names
of pictures to be output. Required if SELECT =
ONLY or EXCEPT.
SELECT C*8 Which pictures in the graphics file to export.:
ALL = Export all pictures on import graphics
file
ONLY = Export only the pictures specified in
NAMPIC
EXCEPT = Export all pictures except those
specified by NAMPIC
NUMPIC I Number of pictures to transfer from the graphics

file to the neutral file. Required if SELECT =
ONLY or EXCEPT.
LEVRPT I Type of status report:
0 = No status report
1 = Status report output to unit LUNSTA
specified by SIISIL
LUNZGF I Number of logical unit on which to open the
graphics file.
Range Options: 099
Recommend: 27
LUNFLT I Number of logical unit on which to open the
neutral file.
Range Options: 099
Recommend: 99
80 Graphics Utilities: Internal Routines S2ZGOT R2003.0

Graphic Routines
S3GELM
Function Obtain the next valid graphics element from a picture

This subroutine returns the next valid graphics element decoded from a
picture.
Note Text is positioned by the method designated by ITXJUS, at the location

specified by XARRAY,YARRAY.
If ITXJUS = 1, the lower left corner of the text string is positioned at
the specified coordinate.
If ITXJUS = 2, the lower right corner of the text string is positioned at
If ITXJUS = 3, the center of the text string is positioned at the
specified coordinate.
Environment A call to SOGLBG to retrieve the next graphics feature must be done
before this routine is called.
Format CALL S3GELM (

1 LENARY , CTXSTR , ADRSTR , QGREND, QWINDW ,
2 QVTSYM , ITYELM , ITMCLR , ITXFNT , ITXJUS ,
3 NUMCHR , ITXCLR , ILINPAT , LINWID , LINCLR ,
4 IFILCL , IVTSYM , NUMPTS , APID , APLEN ,
5 MARKER , XARRAY , YARRAY , SYMANG, SYMHGT ,
6 TXTANG , TXTHGT , DASLEN , DASGAP , HACLEN ,
7 HACGAP , HACDIR , XWINDW , YWINDW, ISTAT )
Input Arguments
LENARY I Length of output arrays.
Output Arguments
CTXSTR C*80 String containing output text, left justified.
ADRSTR C*512 Application data information.
QGREND L Logical for end of this group of graphics

elements:
.TRUE. = Get the next graphics feature
.FALSE. = No more graphics elements
R2003.0 Graphics Utilities: Internal Routines S3GELM 81


QWINDW L Whether there is a clipping window:

.TRUE. = Clipping window is defined by XWINDW
and YWINDW
.FALSE. = No clipping window
QVTSYM L Whether to post a symbol at each vertex of the

line:
.TRUE. = Post symbol at each vertex
.FALSE. = Do not post symbol at each vertex
ITMCLR I Color index of symbol, from color index section

of color table.
ITYELM I Type of element returned:

1 = Lines
2 = Text
3 = Symbols
4 = Colorfilled polygon
ITXFNT I Type of text font. See Appendix C. Symbols,

Fonts, and Line Patterns in the Z-MAP Plus
Reference Manual.
1 = Plain
2 = Roman simplex
3 = Roman complex
4 = Italics
5 = Duplex
ITXJUS I Justification method:

1 = Lower left
2 = Lower right
3 = Center
NUMCHR I Number of characters in text string.
ITXCLR I Color index of text, from color index section of

color table.
LINPAT I Type of line pattern:

1 = Plain
2 = Dashed
3 = Hachured
LINWID I Line width as integer multiple of plain line width.
LINCLR I Color index of lines, from color index section of

color table.
82 Graphics Utilities: Internal Routines S3GELM R2003.0


IFILCL I Color index of polygon fill, from color index

section of color table.
IVTSYM I Symbol code for symbol to post at each vertex of

a line. Needed if ITYELM = 1 and QVTSYM =
.TRUE.
NUMPTS I Number of points in the point string. This is the

number of points returned and may be greater
than LENARY.
APID I Application data identifier.
APLEN I Number of characters of application data

information.
MARKER I Array, of length LENARY, containing the codes

of symbols to post at x,y locations.
XARRAY R Array, of length LENARY, containing the x

locations of points.
YARRAY R Array, of length LENARY, containing the y

locations of points.
SYMANG R Array, of length LENARY, containing the

symbol rotation angles, in degrees.
SYMHGT R Height of symbol, in plotter units (in or cm).
TXTANG R Text rotation, in degrees.

TXTHGT R Text height, in plotter units (in or cm).
DASLEN R Length of dashes, in plotter units (in or cm).
DASGAP R Length of gap between dashes, in plotter units (in

or cm).
HACLEN R Length of hachure lines, in plotter units (in or

cm).
HACGAP R Length of gaps between hachure lines, in plotter

units (in or cm).
R2003.0 Graphics Utilities: Internal Routines S3GELM 83


HACDIR R Direction of hachures:

1 = Pointing uphill
XWINDW R Array, of length 2, containing the x locations of

the lower left and upper right corners of the
clipping rectangle. Given if QWINDW = .TRUE.
YWINDW R Array, of length 2, containing the y locations of

the lower left and upper right corners of the
clipping rectangle. Given if QWINDW = .TRUE.

1 = Warning, length of output array exceeded
1 = Error, problem obtaining the next element
84 Graphics Utilities: Internal Routines S3GELM R2003.0

Graphic Routines
S3IPIC
Function Open a new or old picture

This subroutine opens a picture in the current ZGF graphics file. When
making a new picture, define parameters for the Area of Interest (AOI),
map scale, cartographic projection, etc. See the projections table
following the Output Arguments for correlative arguments. See the
figure following the Output Arguments for reference to picture
coordinates and offsets.
If IBRTIP = 1, (lat/long border), use LONMND, LONMNM,

LONMNS, etc., through LATMXS to describe the
map AOI.
If IBRTIP = 2, (rectilinear border) use VXMIN, VXMAX, VYMIN,

VYMAX to describe the map border.
Three methods are available for defining the map scale:

assign values for map scale using variables XMAPSC and
YMAPSC
compute values for map scale from variables XLONG, YLONG,
and the map boundary
compute values for map scale from variable IABSSC (absolute
scale)
file opened before this routine is called.
Format CALL S3IPIC (

1 PICTUR , IFOLD , IFABSC , IFPRJ , IBRTIP ,
2 IABSSC , LONMND , LONMNM , LONMNS, LONMXD ,
3 LONMXM , LONMXS , LATMND , LATMNM, LATMNS ,
4 LATMXD , LATMXM , LATMXS , IHEM , IUTMCD ,
5 IPJCOD , ISPCOD , IUNCOD , IRADTY , VXMIN ,
6 VXMAX , VYMIN , VYMAX , XOFFST , FREEX ,
7 YOFFST , FREEY , XSCMAP , YSCMAP, XLONG ,
8 YLONG , BOTPAR , TOPPAR , REFLAT , SFLAT ,
9 REFLON , SFLON , FNORTH , FEAST , UNTFAC ,
AXISA , AXISB , AZMTH , SCALE , XLNVEW ,
1 YLNVEW , ISTAT )
R2003.0 Graphics Utilities: Internal Routines S3IPIC 85

Input Arguments
PICTUR C*80 Name of picture.
IFOLD C*3 Whether picture is new or old:

NEW = Open a new picture
OLD = Open an old picture
IFABSC I Type of scale input:

0 = Map/plotter scale input
1 = Absolute scale input
Output Arguments Input for new picture, Output for old picture
IFPRJ I Whether a projection is active:

1 = No projection specified
2 = Projection specified
IBRTIP I Type of border:

1 = Latitude/longitude border
2 = Rectilinear border
IABSSC I Absolute scale used if IFABSC = 1.

Absolute scale can be used only if a map
projection is defined. For an old picture, if IFPRJ
= 2, a calculated value is returned. Otherwise it is
set to zero.
LONMND I Longitude minimum, in degrees or 10,000ths of a

grad.
LONMNM I Longitude minimum, in minutes. Not used for

grads.
LONMNS I Longitude minimum, in seconds. Not used for

grads.
LONMXD I Longitude maximum, in degrees or 10,000ths of

a grad.
LONMXM I Longitude maximum, in minutes. Not used for

grads.
LONMXS I Longitude maximum, in seconds. Not used for

grads.
LATMND I Latitude minimum, in degrees or 10,000ths of a

grad.
86 Graphics Utilities: Internal Routines S3IPIC R2003.0


LATMNM I Latitude minimum, in minutes. Not used for

grads.
LATMNS I Latitude minimum, in seconds. Not used for

grads.
LATMXD I Latitude maximum, in degrees or 10,000ths of a

grad.
LATMXM I Latitude maximum, in minutes. Not used for

grads.
LATMXS I Latitude maximum, in seconds. Not used for

grads.
IHEM * I Hemisphere. For an old picture, if IPJCOD = 1, a
value of 1 or 2 is returned. Otherwise it is set to
zero.
1 = Northern
2 = Southern
IUTMCD * I UTM zone number. Used if IPJCOD = 1. (See

Appendix G. Mapping and Cartographic
Projections in the Z-MAP Plus Reference
Manual.)



Conformal
standard parallels
standard parallel
Mercator
2 = Degrees and General Transverse Mercator
4 = Degrees and Conformal Lambert with one
standard parallel
5 = Degrees and Conformal Lambert with two
standard parallels
13 = Degrees and Oblique Transverse
Mercator
Conformal


ISPCOD * I Reference spheroid:

1 = User defined
2 = Everest 1830
4 = Bessel 1841
5 = Airy 1858
6 = Clarke 1858
7 = Clarke 1866
8 = Clarke 1880
9 = Hayford 1909
11 = Hough 1956
13 = Kaula 1961
14 = IUGG 1967 (Australian National 1967/
16 = WGS-72 1972
17 = IUGG 1975
18 = Helmert
19 = Ghana National
20 = WGS-84 (GRS-80)

1 = User defined
2 = Meters
3 = Feet
4 = Yards
5 = Inches
6 = Kilometers
7 = Nautical miles
8 = Statute miles
9 = U S Survey feet

1 = Equatorial
3 = Equal Volume
4 = Gaussian
VXMIN D Minimum x value, in engineering units.
VXMAX D Maximum x value, in engineering units.
VYMIN D Minimum y value, in engineering units.
VYMAX D Maximum y value, in engineering units.


XOFFST R Border width around left of map, in plotter units

(in or cm).
FREEX R Border width around right of map, in plotter units

(in or cm).
YOFFST R Border width below map, in plotter units (in or

cm).
FREEY R Border width above map, in plotter units (in or

cm).
XSCMAP R Map scale x direction, in map units per plotter

unit.
YSCMAP R Map scale y direction, in map units per plotter

units.
XLONG R The x direction AOI length, in plotter units (in or

cm).
(VXMAXVXMIN)/XSCMAP.
YLONG R The y direction AOI length, in plotter units (in or

cm).
(VYMAXVYMIN)/YSCMAP.
BOTPAR * R Standard parallel closest to the equator (least), in

degrees.
TOPPAR * R Standard parallel farthest from the equator

(greatest), in degrees.

NOTE: Set this variable to a value greater than
0.0.

NOTE: Set this variable to a value greater than 0.0.


UNTFAC * R Projected coordinates units factor. Needed only if

IUNCOD = 1.
AXISA * R Semimajor axis A. Needed only if ISPCOD = 1.
AXISB * R Semiminor axis B. Needed only if ISPCOD = 1.
XLNVEW R The x direction length of the whole plot.

XLNVEW = XOFFST + XLONG + FREEX.
YLNVEW R The y direction length of the whole plot.

YLNVEW = YOFFST + YLONG + FREEY.

1 = Error, opening picture
2 = Error, reading picture header
3 = Error, invalid use of absolute scale
4 = Error, invalid picture type
5 = Error, problem with old picture
6 = Error, problem with new picture
Note: Map projection is required for absolute
scale.

Graphic Routines
S3NPIC
Function Open a new picture

This subroutine opens a new picture on the current graphics file. When
making a new picture, define parameters for the Area of Interest (AOI),
map scale, cartographic projection, etc. See the projections table
following the Output Arguments for correlative arguments. See the
figure following the Output Arguments for reference to picture
If IBRTIP = 1, (lat/long border), use LONMND, LONMNM,
LONMNS, etc., through LATMXS to describe the
map AOI.
If IBRTIP = 2, (rectilinear border) use VXMIN, VXMAX, VYMIN,
VYMAX to describe the map border.
Three methods are available for defining the map scale:

assign values for map scale using variables XMAPSC and
YMAPSC
compute values for map scale from variables XLONG, YLONG,
and the map boundary
compute values for map scale from variable IABSSC (absolute
scale)
Note If the left longitude is greater than the right longitude, the map is made
across the dateline.
You cannot map across the dateline if using grads. For grads, left
longitude cannot be greater than right longitude.
Format CALL S2NPIC (

1 PICTUR , IFABSC , IFPRJ , IBRTIP , IABSSC ,
2 LONMND , LONMNM , LONMNS , LONMXD, LONMXM ,
3 LONMXS , LATMND , LATMNM , LATMNS, LATMXD ,
4 LATMXM , LATMXS , IHEM , IUTMCD , IPJCOD ,
5 ISPCOD , IUNCOD , IRADTY , VXMIN , VXMAX ,
6 VYMIN , VYMAX , XOFFST , FREEX , YOFFST ,
7 FREEY , XSCMAP , YSCMAP , XLONG , YLONG ,
8 BOTPAR , TOPPAR , REFLAT , SFLAT , REFLON ,
9 SFLON , FNORTH , FEAST , UNTFAC , AXISA ,
* AXISB , AZMTH , SCALE , XLNVEW, YLNVEW ,
1 ISTAT )
92 Graphics Utilities: Internal Routines S3NPIC R2003.0

Input Arguments
IFABSC I Type of scale input:

0 = Map/Plotter units scale input
1 = Absolute scale input


1 = Latitude/Longitude border
IABSSC I Absolute scale used if IFABSC = 1.

Absolute scale may be used only if a map
projection is defined.

grad.

grads.

grads.

a grad.

grads.

grads.

grad.

grads.

grads.
R2003.0 Graphics Utilities: Internal Routines S3NPIC 93



grad.

grads.

grads.
IHEM * I Hemisphere. Required if IPJCOD = 1:

1 = Northern
2 = Southern
IUTMCD I UTM zone number. (See Appendix G. Mapping
* and Cartographic Projections in the Z-MAP Plus
Reference Manual.)



Conformal
standard parallels
standard parallel
Mercator
standard parallel
standard parallels
Orthotomic Polyconic)
Mercator
Conformal



1 = User defined
2 = Everest 1830
4 = Bessel 1841
5 = Airy 1858
6 = Clarke 1858
7 = Clarke 1866
8 = Clarke 1880
9 = Hayford 1909
11 = Hough 1956
13 = Kaula 1961
16 = WGS-72 1972
17 = IUGG 1975
18 = Helmert
19 = Ghana National
20 = WGS-84 (GRS-80)

1 = User defined
2 = Meters
3 = Feet
4 = Yards
5 = Inches
6 = Kilometers
7 = Nautical miles
8 = Statute miles
9 = U S Survey feet

1 = Equatorial
3 = Equal Volume
4 = Gaussian



(in or cm).

(in or cm).

cm).

cm).
XSCMAP R Map scale x direction, in map/plotter units.
YSCMAP R Map scale y direction, in map/plotter units.
XLONG R The x direction AOI length, in map/plotter units.

(VXMAX VXMIN)/XSCMAP.
YLONG R The y direction AOI length, in map/plotter units.

(VYMAX VYMIN)/YSCMAP.
BOTPAR R Standard parallel closest to equator (least), in

* degrees.
TOPPAR * R Standard parallel farthest from equator (greatest),

in degrees.
FNORTH R False northing.

*
UNTFAC R Projected coordinates units factor. Needed only if

* IUNCOD = 1.


Output Arguments

XLNVEW = XOFFST + XLONG + FREEX.

YLNVEW = YOFFST + YLONG + FREEY.

1 = Error, opening picture.
2 = Error, illegal use of absolute scale.
3 = Error, invalid reference longitude if UTM
ZONE is not specified.
4 = Error, in inverse projection.
5 = Error, insufficient workspace to develop
lat/long border.
6 = Error, less than three points in lat/long
border. Cannot do clipping.
Note: Map projection is required for absolute
scale.

Table 2: Checklist for Projection Arguments and Projection Type

Projection Type



Azimuthal Gnomonic
American Polyconic
Modified Polyconic
Albers Equal Area
Standard Mercator
Van Der Grinten I

Cassini-Soldner
Arguments
Name Description
1
Key:
1
Y = argument required Also serves as a single standard parallel
2
3
specified, default value is used 4 One or the other is required
* User defined

Cutline
(XLNVEW,YLNVEW)
FREEY (VXMAX,VYMAX)
YLNVEW
YLONG
Scaled Area
XOFFST (User units) FREEX
(VXMIN,VYMIN) Unscaled Area

YOFFST (Plotter units)
*
(0.0,0.0) XLONG
XLNVEW
No graphics may appear outside Unscaled Area
Display Area for a Picture
User Units. For example, Northing/Easting, etc.

Used for Scaled area of the picture
Range for x is VXMIN to VXMAX
for y is VYMIN to VYMAX
Length in x is XLONG = (VXMAX VXMIN)
y is YLONG = (VYMAX VYMIN)
Plotter Units. Inches or centimeters

Used for Unscaled area of the picture
Range for x is 0.0 to XLNVEW
for y is 0.0 to YLNVEW
Length in x is XLNVEW
y is YLNVEW
XOFFST Border width around left of map
YOFFST Border width below map
FREEX Border width around right of map
FREEY Border width above map
In General
TOP/BOTTOM Refers to longitude or eastings
LEFT/RIGHT SIDES Refers to latitude or northings

Graphic Routines
S3OPIC
Function Open an old picture

This subroutine opens an old picture on the current graphics file. See
the figure following Output Arguments for reference to picture
Format CALL S3OPIC (

1 PICTUR , IFPRJ , IBRTIP , IABSSC , LONMND ,
2 LONMNM , LONMNS , LONMXD , LONMXM, LONMXS ,
3 LATMND , LATMNM , LATMNS , LATMXD, LATMXM ,
4 LATMXS , IHEM , IUTMCD , IPJCOD , ISPCOD ,
5 IUNCOD , IRADTY , VXMIN , VXMAX , VYMIN ,
6 VYMAX , XOFFST , FREEX , YOFFST , FREEY ,
7 XSCMAP , YSCMAP , XLONG , YLONG , BOTPAR ,
9 FNORTH , FEAST , UNTFAC , AXISA , AXISB ,
* AZMTH , SCALE , XLNVEW , YLNVEW, ISTAT )
Input Arguments
Output Arguments


1 = Latitude/Longitude border
IABSSC I Absolute scale. A value is returned if IFPRJ = 2;

otherwise, it is set to zero.

grad.
R2003.0 Graphics Utilities: Internal Routines S3OPIC 101



grads.

grads.

a grad.

grads.

grads.
LATMND I Latitude minimum, in degrees or integer

10,000ths of a grad.

grads.

grads.

grad.

grads.

grads.
IHEM * I Hemisphere. A value is returned if IPJCOD = 1;

otherwise, it is set to zero:1
1 = Northern
2 = Southern
IUTMCD * I UTM zone number. (See Appendix G. Mapping

and Cartographic Projections in the Z-MAP Plus
Reference Manual.)
102 Graphics Utilities: Internal Routines S3OPIC R2003.0



Conformal
standard parallels
standard parallel
IPJCOD * I Cartographic projection code (cont.):

(cont.) 1 = Degrees and Universal Transverse
Mercator
standard parallel
standard parallels
Mercator
Conformal



1 = User defined
2 = Everest 1830
4 = Bessel 1841
5 = Airy 1858
6 = Clarke 1858
7 = Clarke 1866
8 = Clarke 1880
9 = Hayford 1909
11 = Hough 1956
13 = Kaula 1961
16 = WGS-72 1972
17 = IUGG 1975
18 = Helmert
19 = Ghana National
20 = WGS-84 (GRS-80)

1 = User-supplied
2 = Meters
3 = Feet
4 = Yards
5 = Inches
6 = Kilometers
7 = Nautical miles
8 = Statute miles
9 = U S Survey feet

1 = Equatorial
3 = Equal Volume
4 = Gaussian



(in or cm).

(in or cm).

cm).

cm).
XSCMAP R Map scale x direction, in map/plotter units.
YSCMAP R Map scale y direction, in map/plotter units.

(VXMAX VXMIN)/XSCMAP.

(VYMAX VYMIN)/YSCMAP.
BOTPAR * R Standard parallel closest to equator (least), in

degrees.
TOPPAR * R Standard parallel farthest from equator (greatest),

in degrees.
UNTFAC * R Projected coordinates units factor. Needed only if

IUNCOD =1.



XLNVEW = YOFFST + XLONG + FREEX.

YLNVEW = YOFFST + YLONG + FREEX.

2 = Error, reading picture header
3 = Error, problem with picture
4 = Error, insufficient workspace to develop
lat/long border
5 = Error, less than three points in lat/long
border. Cannot do clipping.


Projection Type



Azimuthal Gnomonic
American Polyconic
Modified Polyconic
Albers Equal Area
Standard Mercator
Van Der Grinten I

Cassini-Soldner
Arguments
Name Description
1
Key
1
2
3
specified, default value is used. 4 One or the other is required
* User defined

Cutline
(XLNVEW,YLNVEW)
FREEY (VXMAX,VYMAX)
YLNVEW
YLONG
Scaled Area

*
(0.0,0.0) XLONG
XLNVEW


y is YLNVEW
In General

Graphic Routines
S4PCIN
Function Obtain general, projection and graphics feature information for a

picture
Since each graphics file is based on size and not on the number of
pictures, this routine should be used in a loop. Use the routine SIPCFL
to obtain a list of picture names.
Environment The ZPI/O and ZIGS environments must be initialized, the graphics
file opened, and all pictures on that file closed before this routine is
called.
Format CALL S3PCIN (

1 NAMPIC , LGBNAM , LGBTYP , LGBNUM, IBRTIP ,
2 IFPRJ , IABSSC , IUTMCD , IPJCOD , ISPCOD ,
3 IUNCOD , LONMND , LONMNM , LONMNS, LONMXD ,
4 LONMXM , LONMXS , LATMND , LATMNM, LATMNS ,
5 LATMXD , LATMXM , LATMXS , IHEM , IDTLN ,
6 IRADTY , VXMIN , VXMAX , XRANGE, XSCMAP ,
7 XLONG , XOFFST , FREEX , XLNVEW, VYMIN ,
8 VYMAX , YRANGE , YSCMAP , YLONG , YOFFST ,
9 FREEY , YLNVEW , BOTPAR , TOPPAR , REFLAT ,
* SFLAT , REFLON , SFLON , FNORTH , FEAST ,
1 UNTFAC , AXISA , AXISB , AZMTH , SCALE ,
2 ISTAT )
Input Arguments
NAMPIC C*80 Name of the picture.
Output Arguments
LGBNAM C*40 Array, of length 50, containing the graphics

feature (LGB) names. For the list of names, see
Appendix A. Graphics Feature Codes in the
LGBTYP I Array, of length 50, containing the graphics

feature (LGB) type numbers. For the list of
codes, see Appendix A. Graphics Feature
Codes in the Z-MAP Plus Reference Manual.
LGBNUM I Number of graphics features.
R2003.0 Graphics Utilities: Internal Routines S4PCIN 109



1 = Latitude/longitude
2 = Rectilinear

IABSSC I Absolute scale. If IFPRJ = 2, an absolute scale is

calculated, otherwise it is set to zero.

Reference Manual.)
110 Graphics Utilities: Internal Routines S4PCIN R2003.0


IPJCOD * I Cartographic projection:

Conformal
standard parallels
standard parallel
Mercator
standard parallel
standard parallels
IPJCOD * I Cartographic projection (cont.):

(cont.) 11 = Currently not used
Mercator
Conformal



1 = User defined
2 = Everest 1830
4 = Bessel 1841
5 = Airy 1858
6 = Clarke 1858
7 = Clarke 1866
8 = Clarke 1880
9 = Hayford 1909
11 = Hough 1956
13 = Kaula 1961
16 = WGS-72 1972
17 = IUGG 19
18 = Helmert
19 = Ghana National
20 = WGS-84 (GRS-80)

1 = User defined
2 = Meters
3 = Feet
4 = Yards
5 = Inches
6 = Kilometers
7 = Nautical miles
8 = Statute miles
9 = U S Survey feet

grad.

grads.

grads.

a grad.

grads.



grads.

grad.

grads.

grads.

grad.

grads.

grads.
IHEM * I Which hemisphere:

0 = Cannot be determined
1 = Northern
2 = Southern
IDTLN I Whether mapping across the dateline:

0 = Not mapping cross the dateline
1 = Mapping across the dateline
XRANGE R Range of x, in engineering units.
XSCMAP R The x direction map scale, in map/plotter units.

(in or cm).

(in or cm).
XLNVEW R The x direction length of whole plot, in plotter

units (in or cm).


YRANGE R Range of x, in engineering units.
YSCMAP R The y direction map scale, in map/plotter units.

cm).

cm).
YLNVEW R The y direction length of whole plot, in plotter

units (in or cm).
BOTPAR R Standard parallel (least).

*
TOPPAR * R Standard parallel (greatest).
SFLAT * R Reference latitude scale factor.
SFLON * R Reference longitude scale factor.

*
UNTFAC R Projected coordinates units factor.

*
AXISA * R Semimajor axis A.
AXISB * R Semiminor axis B.
AZMTH * R Azimuth of central line at skew origin for

Oblique Transverse Mercator.


SCALE * R Scale factor at origin for Oblique Transverse

Mercator.

1 = Error, picture not found
2 = Error, problem obtaining picture
information


Projection Type



Azimuthal Gnomonic
American Polyconic
Modified Polyconic
Albers Equal Area
Standard Mercator
Van Der Grinten I

Cassini-Soldner
Arguments
Name Description
1
Key
1
2
3
* User defined

Graphic Routines
SIEPIC
Function Close the last picture opened

This subroutine insures that a picture is properly closed.
Environment The ZPI/O and ZIGS environments must be initialized and a picture
opened before this routine is called.
Format CALL SIEPIC ( ISTAT )
Output Arguments
1 = Error, problem closing the currently open
picture
R2003.0 Graphics Utilities: Internal Routines SIEPIC 117

Graphic Routines
SIEZGF
Function Close a graphics file

This subroutine terminates operations in a ZGF graphics file. This
subroutine should be called after work on a graphics file is complete so
that another graphics file can be opened.
Format CALL SIEZGF
118 Graphics Utilities: Internal Routines SIEZGF R2003.0

Graphic Routines
SIEZIG
Function Terminate the Z-MAP Interactive Graphics Environment (ZIGS)

This subroutine should be called after all graphics operations have
been completed.
routine is called.
Format CALL SIEZIG
R2003.0 Graphics Utilities: Internal Routines SIEZIG 119

Graphic Routines
SIGLCL
Function Set line color

This subroutine sets the line color. All lines are drawn in the specified
color until the next call to this routine.
Environment The ZPI/O and ZIGS environments must be initialized, and a graphic
Format CALL SIGLCL ( ICOLOR , ISTAT )
Input Arguments
ICOLOR I Color index for drawing lines, from the color
table currently defined.
Range Options: 0255
Output Arguments
1 = Error, invalid line color index
120 Graphics Utilities: Internal Routines SIGLCL R2003.0

Graphic Routines
SIGLIN
Function Draw connected line segments

This subroutine draws line segments in the current units system, using
the currently defined line color, type, and width.
file, a picture, and a graphics feature must be opened before this
routine is called.
Format CALL SIGLIN ( NUMPTS , XCORS , YCORS , ISTAT )
Input Arguments
NUMPTS I Number of points.
XCORS R Array, of length NUMPTS, containing the x
coordinate values.
YCORS R Array, of length NUMPTS, containing the y
coordinate values.
Output Arguments
1 = Error, number of points is zero
R2003.0 Graphics Utilities: Internal Routines SIGLIN 121

Graphic Routines
SIGLPM
Function Set dash line and hachure mark parameters

This subroutine sets the length and gap for dash lines and the length,
gap and direction of hachure marks. All lines or hachures are drawn
with the prescribed values until the next call to this subroutine.
file, picture, and graphics feature must be opened before this routine is
called.
Format CALL SIGLPM (

1 DSHLEN , DSHGAP , HSHLEN , HSHGAP , HSHWAY ,
2 ISTAT )
Input Arguments
DSHLEN R Length of dash.
Default = 0.2 in or 0.5 cm
DSHGAP R Length of gap between dashes.
HSHLEN R Length of hachure marks.
HSHGAP R Length of gap between hachures.
HSHWAY R Direction of hachures:
1 = Pointing uphill
Output Arguments
1 = Error, dash length is negative
2 = Error, dash gap length is negative
3 = Error, hachure length is negative
4 = Error, hachure gap length is negative
122 Graphics Utilities: Internal Routines SIGLPM R2003.0

Graphic Routines
SIGLTY
Name SIGLTY
Function Set line type

This subroutine sets the line type. All line segments drawn are type
LTYP until the next call to this routine.
routine is called.
Format CALL SIGLTY ( LTYP , ISTAT )
Input Arguments
LTYP I Type of line:
1 = Plain
2 = Dashed
3 = Hachured
Output Arguments
1 = Error, invalid line type
R2003.0 Graphics Utilities: Internal Routines SIGLTY 123

Graphic Routines
SIGLWD
Function Set line width

This subroutine sets the line width. All lines are drawn with a width
determined by WIDTH until the next call to this routine.
routine is called.
Format CALL SIGLWD ( WIDTH , ISTAT )
Input Arguments
WIDTH R Line width. This is a scalar by which the standard
line width is multiplied to get a new line width.
Range Options: 18
Output Arguments
1 = Error, invalid line width
124 Graphics Utilities: Internal Routines SIGLWD R2003.0

Graphic Routines
SIGMCL
Function Set marker color

This subroutine sets the marker color. All marker symbols are drawn in
the specified color until the next call to this routine.
file, a picture and a graphics feature must be opened before this routine
is called.
Format CALL SIGMCL ( ICOLOR , ISTAT )
Input Arguments
ICOLOR I Color index for drawing markers, from the color
Range Options: 0255
Output Arguments
1 = Error, invalid marker color index
R2003.0 Graphics Utilities: Internal Routines SIGMCL 125

Graphic Routines
SIGMHT
Function Set marker height

This subroutine sets the marker height. All marker symbols are drawn
the specified height until the next call to this routine.
routine is called.
Format CALL SIGMHT ( HEIGHT , ISTAT )
Input Arguments
HEIGHT R Height for markers, in plotter units (in or cm).
Output Arguments
1 = Error, marker height is less than or equal
to zero
126 Graphics Utilities: Internal Routines SIGMHT R2003.0

Graphic Routines
SIGMTY
Function Set marker type

This subroutine sets marker type. All marker symbols drawn are of the
designated type until the next call to this routine.
routine is called.
Format CALL SIGMTY( MARKER , ISTAT )
Input Arguments
MARKER I Symbol code for type of marker. (See Appendix
C. Symbols, Fonts, and Line Patterns in the
Output Arguments
1 = Error, invalid marker type
R2003.0 Graphics Utilities: Internal Routines SIGMTY 127

Graphic Routines
SIGPCL
Function Set polygon fill color

This subroutine sets the polygon fill color. All filled polygons are
drawn in the color designated until the next call to this routine.
routine is called.
Format CALL SIGPCL ( ICOLOR , ISTAT )
Input Arguments
ICOLOR I Color index for filling polygons, from the color
Range Options: 0255
Output Arguments
1 = Error, invalid polygon color index
128 Graphics Utilities: Internal Routines SIGPCL R2003.0

Graphic Routines
SIGPDF
Function Set defaults for lines, markers, text, and polygons

This subroutine sets the defaults for the line color, type, and width;
marker symbol color, height, and type; polygon fill color; and text
color, font, justification, and rotation angle. You can call this routine
multiple times to reset these values.
Values of zero are set with the defined defaults. Otherwise valid user
inputs are used.
file, a picture, and a graphic feature must be opened before this routine
is called.
Format CALL SIGPDF (

1 KLNCLR , KLNTYP , KMKCLR , KMKTYP , KTXTCL ,
2 KTXTFO , KTXTJU , KPOLCL , KSCLTY , WDLINE ,
3 HTMARK , HTTEXT , ROTEXT , DSHLEN , DSHGAP ,
4 HSHLEN , HSHGAP , HSHWAY , ISTAT )
Input Arguments
KLNCLR I Color index for drawing lines, from the color

Default = 1 (black on plotter, white on screen)
Range Options: 0255
KLNTYP I Type of line:

1 = Plain
2 = Dashed
3 = Hachured
Default = 1
KMKCLR I Color index for drawing marker symbols, from

the color table currently defined.
Range Options: 0255
KMKTYP I Symbol code for marker type. (See Appendix C.

Symbols, Fonts, and Line Patterns in the
Default = 1 (little cross)
Range Options: 1100
R2003.0 Graphics Utilities: Internal Routines SIGPDF 129


KTXTCL I Color index for drawing text, from the color table
currently defined.
Range Options: 0255
KTXTFO I Type of text font. (See Appendix C. Symbols,

Reference Manual.)
1 = Plain
2 = Roman simplex
3 = Roman complex
4 = Italics
5 = Duplex
Default = 1
KIXTJU I Text justification:

1 = Lower left
2 = Lower right
3 = Centered
Default = 1
KPOLCL I Color index for drawing colorfilled polygons,

from the color table currently defined.
Range Options: 0255
KSCLTY I Coordinate system:

1 = Engineering coordinates
2 = Plotter coordinates (in or cm)
Default = 2
WDLINE R Line width multiplier. This is a scalar by which

the standard line width is multiplied to get a new
line width
Default = 1.0
HTMARK R Marker height, in plotter units (in or cm).

HTTEXT R Text height, in plotter units (in or cm).

130 Graphics Utilities: Internal Routines SIGPDF R2003.0


ROTEXT R Text rotation angle, in degrees.

Default = 0.0
DSHLEN R Length of the solid part of the dash, in plotter

units (in or cm).
DSHGAP R Length of the gap part of the dash, in plotter units

(in or cm).

or cm).
HSHGAP R Distance between hachures, in plotter units (in or

cm).

1 = Pointing uphill
Default = 1.0
Output Arguments
1 = Error, invalid scale type
2 = Error, invalid color index
3 = Error, invalid line type
4 = Error, invalid line width multiplier
5 = Error, invalid marker type
6 = Error, invalid text font
7 = Error, invalid text justification
8 = Error, invalid text rotation
9 = Error, marker height is negative
10 = Error, text height is negative
11 = Error, dash length is negative
12 = Error, dash gap is negative
13 = Error, hachure length is negative
14 = Error, hachure gap is negative
15 = Error, invalid hachure direction
R2003.0 Graphics Utilities: Internal Routines SIGPDF 131

Graphic Routines
SIGPFL
Function Draw a shaded or colorfilled polygon

This subroutine draws a shaded or colorfilled polygon. The given
polygon is colorfilled with the current polygon fill color.
The polygon must be closed before this routine is called, i.e., last point
equals first point.
is called.
Format CALL SIGPFL ( NVERT , XCORS , YCORS , ISTAT )
Input Arguments
NVERT I Number of vertices of the polygon.
XCORS R Array, of length NVERT, containing the x
coordinates of polygon vertices, in the currently
defined coordinate system.
YCORS R Array, of length NVERT, containing the y
coordinates of polygon vertices, in the currently
defined coordinate system.
Output Arguments
1 = Error, number of vertices is zero
2 = Error, graphics segment is not open
3 = Error, polygon is not closed
4 = Error, maximum number of vertices
allowed has been exceeded
5 = Error, problem colorfilling the polygons
132 Graphics Utilities: Internal Routines SIGPFL R2003.0

Graphic Routines
SIGSCL
Function Close current graphics feature

routine is called.
Format CALL SIGSCL ( ISTAT )
Output Arguments
1 = Error, closing graphic feature
2 = Error, no graphics feature is currently
open
R2003.0 Graphics Utilities: Internal Routines SIGSCL 133

Graphic Routines
SIGSCS
Function Define coordinate system

This subroutine defines the coordinate system applied to all
coordinates input to graphics subroutines until the next call to this
subroutine.
routine is called.
Format CALL SIGSCS ( ISCALE , ISTAT )
Input Arguments
ISCALE I Type of coordinate system:
1 = Engineering units
2 = Plotter units (in or cm)
Output Arguments
1 = Error, invalid scale type
134 Graphics Utilities: Internal Routines SIGSCS R2003.0

Graphic Routines
SIGSDL
Function Delete a graphics feature from a picture file

This subroutine deletes all instances of a particular type of a graphics
feature from the open picture. If SIPCCP is done afterwards to the
same picture, the actual graphic segments are deleted from the picture
file, rather than just from what is being displayed.
routine is called.
Format CALL SIGSDL ( ISEGTY , ISTAT )
Input Arguments
ISEGTY I Graphics feature number for the graphics feature
to delete. (See Appendix A. Graphics Feature
Codes in the Z-MAP Plus Reference Manual.)
Output Arguments
1 = Warning, graphics feature has been closed
1 = Error, invalid graphics feature number
2 = Error, unsuccessful delete
3 = Error, problem closing graphics feature
R2003.0 Graphics Utilities: Internal Routines SIGSDL 135

Graphic Routines
SIGSOP
Function Open a new graphics feature

This subroutine opens a new graphics feature. If a feature is currently
open, it is closed before opening a new one. All graphics following a
call to this routine are assumed to belong to the segment.
routine is called.
Format CALL SIGSOP ( ISEGTY , ISTAT )
Input Arguments
ISEGTY I Graphics feature number for the graphics feature
to open. (See Appendix A. Graphics Feature
Output Arguments
1 = Error, invalid graphics feature number
2 = Error, problem opening graphics feature
136 Graphics Utilities: Internal Routines SIGSOP R2003.0

Graphic Routines
SIGTCL
Function Set text color

This subroutine sets text color. All text is drawn in the designated color
until the next call to this routine.
is called.
Format CALL SIGTCL ( ICOLOR , ISTAT )
Input Arguments
ICOLOR I Color index for drawing text, from the color table
currently defined.
Range Options: 0255
Output Arguments
1 = Error, invalid text color index
R2003.0 Graphics Utilities: Internal Routines SIGTCL 137

Graphic Routines
SIGTFO
Function Set text font

This subroutine sets the text font. All text is drawn with the designated
font until the next call to this routine.
routine is called.
Format CALL SIGTFO ( IFONT , ISTAT )
Input Arguments
IFONT I Type of text font. (See Appendix C. Symbols,
Reference Manual.)
1 = Plain
2 = Roman simplex
3 = Roman complex
4 = Italics
5 = Duplex
Output Arguments
1 = Error, invalid font type
138 Graphics Utilities: Internal Routines SIGTFO R2003.0

Graphic Routines
SIGTHT
Function Set text height

This subroutine sets text height. All text is drawn at the designated
height until the next call to this routine.
routine is called.
Format CALL SIGTHT ( HEIGHT , ISTAT )
Input Arguments
HEIGHT R Height of text, in plotter units (in or cm).
Output Arguments
1 = Error, text height is less than or equal to
zero
R2003.0 Graphics Utilities: Internal Routines SIGTHT 139

Graphic Routines
SIGTJU
Function Set text justification

This subroutine sets text justification. Text is positioned by the method
designated by JUSTIF, at the location specified by SIGTXT, until the
next call to this routine.
If JUSTIF = 1, the lower left corner of the text string is positioned at
If JUSTIF = 2, the lower right corner of the text string is positioned at
If JUSTIF = 3, the center of the text string is positioned at the
specified coordinate.
routine is called.
Format CALL SIGTJU ( JUSTIF , ISTAT )
Input Arguments
JUSTIF I Justification method:
1 = Lower left
2 = Lower right
3 = Center
Output Arguments
1 = Error, invalid justification type
140 Graphics Utilities: Internal Routines SIGTJU R2003.0

Graphic Routines
SIGTRO
Name SIGTRO
Function Set text rotation

This subroutine rotates all text strings at an angle defined by ANGLE
until the next call to this routine.
routine is called.
Format CALL SIGTRO ( ANGLE , ISTAT )
Input Arguments
ANGLE R Angle at which to draw text, in degrees from
horizontal.
Output Arguments
1 = Error, invalid text rotation angle
R2003.0 Graphics Utilities: Internal Routines SIGTRO 141

Graphic Routines
SIGTXT
Function Draw text

This subroutine draws text. The text string contained in TEXT is drawn
at the location defined by XCORS and YCORS, with the currently
defined height, color, font, justification method, and rotation angle.
routine is called.
Format CALL SIGTXT(

1 TEXT , NCHAR , XCORS , YCORS , ISTAT )
Input Arguments
TEXT C*80 Text string of length NCHAR.
NCHAR I Number of characters in text string.
Range Options: 080
XCORS R The x coordinate of text.
YCORS R The y coordinate of text.
Output Arguments
142 Graphics Utilities: Internal Routines SIGTXT R2003.0


Projection Type



Azimuthal Gnomonic
American Polyconic
Modified Polyconic
Albers Equal Area
Standard Mercator
Van Der Grinten I

Cassini-Soldner
Arguments
Name Description
1
Key
1
2
3
O = argument optional.If not Hemisphere defines false northing for UTM
* User defined
R2003.0 Graphics Utilities: Internal Routines SIGTXT 143

Cutline
(XLNVEW,YLNVEW)
FREEY (VXMAX,VYMAX)
YLNVEW
YLONG
Scaled Area

*
(0.0,0.0) XLONG
XLNVEW


y is YLNVEW
In General
144 Graphics Utilities: Internal Routines SIGTXT R2003.0

Graphic Routines
SIIZGF
Function Open a graphics file
routine is called.
Format CALL SIIZGF (

1 ZGFNAM , HISNEW , IFNEW , HISOLD , ISTAT )
Input Arguments
ZGFNAM C*80 Disk filename of graphics file. This name is a
dummy variable on systems without dynamic file
allocation, but good for documentation.
HISNEW C*80 Header for the new graphics file.
IFNEW C*3 File type:
NEW = Open a new graphics file
OLD = Open an old graphics file
Output Arguments
HISOLD C*80 Header of an old graphics file.
1 = Error, opening graphics file
2 = Error, invalid graphics file type
R2003.0 Graphics Utilities: Internal Routines SIIZGF 145

Graphic Routines
SIIZIG
Function Initialize the Z-MAP Interactive Graphics Environment (ZIGS)
Environment The ZPI/O environment must be initialized before this routine is called.
Format CALL SIIZIG
146 Graphics Utilities: Internal Routines SIIZIG R2003.0

Graphic Routines
SIOVLY
Function Overlay maps or generate index maps

This subroutine takes the parameters passed from a driver routine for
overlaying graphics. It then copies the picture as instructed.
file and Copy To picture opened before this routine is called.
Format CALL SIOVLY (

1 ZGFAUX , PICFRM , IMODE , NOTZGF , NTYPS ,
2 LGBTYP , NDXPOS , XLWLF , YLWLF , HEIGHT ,
3 ISTAT )
Input Arguments
ZGFAUX C*80 Name of the auxiliary graphics file, if used.
PICFRM C*80 Name of the Copy From picture.
IMODE I Type of overlay graphics:

1 = Copy one picture to another picture
2 = Overlay one picture onto another picture
4 = Overlay an index map or any other picture
below the Copy To picture AOI. The
height of the index map must be less than
the height of the Copy To picture
NOTZGF I Whether the Copy From picture is in an

auxiliary graphics file rather than the same one as
the Copy To picture:
0 = An auxiliary graphics file is used
1 = No auxiliary graphics file is used
NTYPS I Number of types of graphics features to be

copied.
LGBTYP I Array, of length 40, containing the codes for the

graphics features to be copied, one for each
feature. For a list of codes and their descriptions,
see Appendix A. Graphics Feature Codes in the
Z-MAP Plus Reference Manual. If all available
types of features are to be copied, set NTYPS = 1
and set LGBTYP(1) = 100.
R2003.0 Graphics Utilities: Internal Routines SIOVLY 147


NDXPOS I Position of the index map. Used if IMODE = 4.

1 = Position the index map in the lower left
corner of the Copy To picture
2 = Position the index map in the lower right
corner of the Copy To picture
3 = The x,y coordinates of the lower left
corner of the index map are given by
XLWLF and YLWLF
XLWLF R The x coordinate for the lower left corner of the

index map overlay, in plotter units. Used if
IMODE = 4 and NDXPOS = 3.
YLWLF R The y coordinate for the lower left corner of the

index map overlay, in plotter units. Used if
IMODE = 4 and NDXPOS = 3.
HEIGHT R The height of the index map, in plotter units.

Used if IMODE = 4. The height of the index map
must be less than the y offset of the Copy To
picture.
Output Arguments
1 = Error, copying graphics information
2 = Error, problem positioning index map
148 Graphics Utilities: Internal Routines SIOVLY R2003.0

Graphic Routines
SIPCAS
Function Assemble/overlay a picture

This subroutine is a general purpose assembly and overlay routine.
Overlays and composite maps can be created using this routine in
conjunction with the default setup routine. See the illustration
following Output Arguments for the relationship between the Copy
From and Copy To space.
Note The Copy From graphics file is opened on logical unit 27 and the
Copy To graphics file is opened on logical unit 28.
files and pictures exist and are closed.
Format CALL SIPCAS (

1 PICFRM , PICTO , ZGFFRM , ZGFTO , IFSAME ,
2 LGBOUT , LGBNUM , LGBTYP , IFBORD , ICLIP ,
3 XLL , YLL , RESCL , ISTAT )
Input Arguments
PICFRM C*80 Name of input Copy From picture.
PICTO C*80 Name of output Copy To picture.
ZGFFRM C*80 Name of input Copy From graphics file.
ZGFTO C*80 Name of output Copy To graphics file.
IFSAME L Logical for whether both pictures are on the

same graphics file:
.TRUE. = Pictures are in the same graphics file
.FALSE. = Pictures are in different graphics files
LGBOUT I Maintain the individual graphics features or

copy as a single block:
1 = Copy into a single feature
2 = Maintain divisions
LGBNUM I Number of graphics features to copy.
R2003.0 Graphics Utilities: Internal Routines SIPCAS 149



graphics features to be copied. To copy entire
picture set LGBTYP(1) to a negative number.
For a list of codes, see Appendix A. Graphics
Feature Codes in the Z-MAP Plus Reference
Manual.
IFBORD I Whether to draw the cutline around the copied

picture:
0 = Do not draw the cutline
1 = Draw the cutline
ICLIP I Whether to clip to Copy To picture border.

0 = Do not clip picture
1 = Clip picture
XLL R The x coordinate of lower left corner of Copy

From picture in plotter units (in or cm) for the
Copy To picture. See the illustration following
the Output Arguments.
YLL R The y coordinate of lower left corner of Copy

From picture in plotter units (in or cm) for the
Copy To picture. See the illustration following
the Output Arguments.
RESCL R Rescaling factor between plotter units in Copy

From and Copy To pictures.
Output Arguments
1 = Warning, clipping is currently
unavailable. Reset to zero.
1 = Error, logical not properly set.
2 = Error, performing the copy process.
3 = Error, from copying process.
4 = Error, closing copy process.
150 Graphics Utilities: Internal Routines SIPCAS R2003.0

Cutline
(XLNVEW,YLNVEW)
Border FREEY (VXMAX,VYMAX)

YLNVEW
YLONG
XOFFST FREEX
*
(XLL,YLL)
(VXMIN,VYMIN)
YOFFST
(0.0,0.0) XLONG
XLNVEW
Copy To Space
Cutline
(XLNVEW,YLNVEW)

YLNVEW
YLONG
Scaled Area

*
(0.0,0.0) XLONG
XLNVEW
Copy From Space
Copy To Space and Copy From Space
R2003.0 Graphics Utilities: Internal Routines SIPCAS 151


Scaled area of the picture

Unscaled area of the picture
y is YLNVEW
In General
152 Graphics Utilities: Internal Routines SIPCAS R2003.0

Graphic Routines
SIPCCP
Function Copy all or part of a picture to another picture

This subroutine copies all of a picture or just a selected few logical
graphics blocks to another picture on the same, an old, or a new
graphics file. The graphics features can be copied individually or into a
single feature (the graphics feature type is Index Map).
If an auxiliary graphics file is used, it should be closed before calling
this routine. It is opened on logical unit 28.
file which contains the Copy From picture must be open. The Copy
From picture is closed by this routine.
Format CALL SIPCCP (

1 PICFRM , PICTO , ZGFAUX , HISNEW , NOTZGF ,
2 LGBOUT , LGBNUM , LGBTYP , ISTAT )
Input Arguments
PICFRM C*80 Name of the input Copy From picture.
PICTO C*80 Name of the new Copy To picture. If blank, the
Copy From picture name is to be used.
ZGFAUX C*80 Name of the output Copy To graphics file.
Blanked if the same graphics file is to be used.
HISNEW C*80 History for the new graphics file.
NOTZGF I Which graphics file to copy the new picture into:
0 = Same graphics file
1 = Old graphics file
2 = New graphics file
LGBOUT I Maintain the individual graphics features or copy
as a single block:
1 = Copy into a single feature
2 = Maintain divisions
LGBNUM I Number of graphics features to copy. Set to zero
if all graphics features are to be copied and
LGBTYP(1) is set to a negative number.
graphics features to be copied. To copy entire
picture, set LGBTYP(1) to a negative number.
For a list of codes, see Appendix A. Graphics
Feature Codes in the Z-MAP Plus Reference
Manual.
R2003.0 Graphics Utilities: Internal Routines SIPCCP 153

Output Arguments

1 = Error, problem initializing copying
3 = Error, problem opening Copy To
graphics file
4 = Error, problem opening picture
5 = Error, problem copying headers
6 = Error, problem copying picture
7 = Error, problem closing picture
8 = Error, copying to the same graphics file
and the Copy To picture name is the same
as the Copy From picture
9 = Error, invalid type of graphics file to copy
to
154 Graphics Utilities: Internal Routines SIPCCP R2003.0

Graphic Routines
SIPCDF
Function Compute four corners of one picture relative to another picture for
assembly/overlay
This subroutine computes defaults used to perform picture composition
and overlay tasks in the ZPI/O environment. Its primary function is to
provide the lower left corner of the Copy From picture in terms of the
Copy To space. (See the illustration following Output Arguments.)
Note The arrays XBOUND and YBOUND are stored as follows:

(X1,Y2) (X2,Y2)
( XBOUND(1) YBOUND(1) ) = (X1, Y1)
(X1,Y1) (X2,Y1)
The Copy From graphics file is opened on logical unit 27, and the
Copy To graphics file is opened on logical unit 28.
files and pictures must exist and be closed.
Format CALL SIPCDF (

1 PICFRM , PICTO , ZGFFRM , ZGFTO , IFSAME ,
2 IRESCL , IFCOFS , XLLIN , YLLIN , XLRIN ,
3 YLRIN , RESCL , XLLOT , YLLOT , RESCOT ,
4 XBOUND , YBOUND , ISTAT )
Input Arguments
PICFRM C*80 Name of input Copy From picture.
PICTO C*80 Name of output Copy To picture.
ZGFFRM C*80 Name of graphics file containing input Copy
From picture.
ZGFTO C*80 Name of graphics file to contain output Copy To
picture.
IFSAME L Logical for whether both pictures are in the same
graphics file:
.TRUE. = Pictures are in the same graphics file
.FALSE. = Pictures are in different graphics files
R2003.0 Graphics Utilities: Internal Routines SIPCDF 155


IRESCL I Type of rescaling used to position picture:
0 = No rescaling
1 = Use width
2 = Use rescaling factor
3 = Rescale for overlay
IFCOFS I Positioning method:
1 = Use lower left corner of cutline
2 = Use lower left corner of map border
3 = Position for overlay
XLLIN R The x coordinate of lower left corner of Copy
From picture in the Copy To picture coordinate
space. Needed if IRESCL = 0, 1, or 2.
YLLIN R The y coordinate of lower left corner of Copy
From picture in the Copy To picture coordinate
space. Needed if IRESCL = 0, 1, or 2.
XLRIN R The x coordinate of lower right corner of Copy
From picture in Copy To picture coordinate
space. Needed if IRESCL = 1.
YLRIN R The y coordinate of lower right corner of Copy
From picture in Copy To picture coordinate
space. Needed if IRESCL = 1.
RESCL R Input rescaling factor. Needed if IRESCL = 2.
Output Arguments
XLLOT R Output x coordinate of lower left corner. Output if
IFCOFS = 3, overlay.
YLLOT R Output y coordinate of lower left corner. Output if
IFCOFS = 3, overlay.
RESCOT R Output rescaling factor. Output if IRESCL = 1 or
3.
XBOUND R Array, of length 4, containing the x coordinates of
the box around Copy From picture given in Copy
To coordinate space.
YBOUND R Array, of length 4, containing the y coordinates of
the box around Copy From picture given in Copy
To coordinate space.
156 Graphics Utilities: Internal Routines SIPCDF R2003.0


ISTAT R Status flag:
1 = Error, logical not properly set
2 = Error, problem initializing pictures and
graphics files
3 = Error, problem calculating box coordinates
4 = Error, problem closing pictures and
graphics files
Cutline
(XLNVEW,YLNVEW)
Copy To
Space
YLNVEW
YLONG
XOFFST FREEX
*
(XLLIN,YLLIN) (XLRIN,YLRIN)
(VXMIN,VYMIN)
YOFFST
(0.0,0.0) XLONG
XLNVEW
Cutline
(XLNVEW,YLNVEW)

Copy From
Space
YLNVEW
YLONG
Scaled Area

*
(0.0,0.0) XLONG
XLNVEW
Copy To Space and Copy From Space
R2003.0 Graphics Utilities: Internal Routines SIPCDF 157



y is YLNVEW
In General
158 Graphics Utilities: Internal Routines SIPCDF R2003.0

Graphic Routines
SIPCDL
Function Mark a picture for deletion

This subroutine marks a picture on the current graphics file for
deletion.
If the graphics file is compressed (as described in SIZGCM on page
163), the picture information for those pictures marked for deletion is
erased.
file containing the picture(s) to be deleted must be open before this
routine is called.
Format CALL SIPCDL ( NAMPIC , ISTAT )
Input Arguments
NAMPIC C*80 Name of the picture to be marked for deletion.
Output Arguments
1 = Error, problem reading picture header
2 = Error, problem writing picture header
R2003.0 Graphics Utilities: Internal Routines SIPCDL 159

Graphic Routines
SIPCFL
Function Obtain a picture name by picture index
routine is called. The graphics file is opened and closed by this routine.
Format CALL SIPCFL (

1 NAMZGF , NUMPIC , INXPIC , NAMPIC , NUMPCS,
2 ISTAT )
Input Arguments
NAMZGF C*80 Name of the graphics file.
NUMPIC I Number of pictures to obtain information for.
Range Options: >0
INXPIC I Array, of length NUMPIC, containing the
indices of the pictures for which information is to
be obtained. Set INXPIC(1) to NUMPIC or a
large negative number to obtain all pictures.
Output Arguments
NAMPIC C*80 Array, of length NUMPIC, containing the names
of the pictures associated with the picture
indices.
NUMPCS I Number of pictures for which actual information
was obtained.
2 = Warning, picture does not exist for that
index.
1 = Warning, number of pictures requested is
too large. Resetting to actual number of
pictures.
1 = Error, invalid picture index.
2 = Error, problem opening graphics file.
160 Graphics Utilities: Internal Routines SIPCFL R2003.0

Graphic Routines
SIPCRN
Function Rename a picture

This subroutine takes an old picture on the current graphics file and
renames it to the name provided.
Format CALL SIPCRN ( NAMOLD , NAMNEW , ISTAT )
Input Arguments
NAMOLD C*80 Name of the picture to be renamed.
NAMNEW C*80 New name for the picture.
Output Arguments
1 = Error, old picture not found
2 = Error, new picture name blank or same as
old picture
3 = Error, no names on the file
4 = Error, new picture name already exists
5 = Error, problem renaming file
161 Graphics Utilities: Internal Routines R2003.0

Graphic Routines
SIRPIC
Function Open an old picture in read-only mode

This subroutine opens an old picture on the current graphics file for
reading only, such as to display or plot an old picture.
Format CALL SIRPIC ( PICNAM , ISTAT )
Input Arguments
PICNAM C*80 Name of the picture.
Output Arguments
R2003.0 Graphics Utilities: Internal Routines 162

Graphic Routines
SIZGCM
Function Compress a graphics file

This subroutine takes an old graphics file with pictures that have been
marked for deletion and compresses it into another graphics file with
only the current pictures, using the history and other information from
the old graphics file.
The uncompressed graphics file is opened on logical unit 27 and the
new compressed graphics file is opened on logical unit 28.
files closed before this routine is called.
Format CALL SIZGCM ( ZGFOLD , ZGFNEW , ISTAT )
Input Arguments
ZGFOLD C*80 Name of the graphics file to be compressed.
ZGFNEW C*80 Name of the new compressed graphics file.
Output Arguments
1 = Error, problem opening old graphics file
2 = Error, problem initializing copy
3 = Error, problem switching from one
graphics file to the other
4 = Error, problem opening new graphics file
5 = Error, problem compressing graphics file

Output Arguments Which of these tables is the correct one?

3 = Warning, problem copying graphics
segments
2 = Warning, problem writing picture
information
1 = Warning, problem opening picture
1 = Error, number of pictures is zero
2 = Error, invalid logical unit
3 = Error, opening neutral file

Graphic Routines
SOGCLS
Name SOGCLS
Function Obtain the color representation for a color index

This subroutine, for a given color index on the color table associated
with the currently open picture, returns the percentage of red, green
and blue as decimal fractions.
Environment A call to S3GELM to obtain the next graphics element must be done
Format CALL SOGCLS (

1 NDXCLR , REDPCT , GRNPCT , BLUPCT , ISTAT )
Input Arguments
NDXCLR I Color index.
Range Options: 0255
Output Arguments
REDPCT R Fraction red.
GRNPCT R Fraction green.
BLUPCT R Fraction blue.
1 = Error, no color table on picture
2 = Error, invalid color index

Graphic Routines
SOGEND
Function Terminate the ZPI/O output graphics environment

This subroutine deactivates the output graphics subsystem. It can be
reactivated by calling SOGINT.
Environment This subroutine should be called after a picture has been completely
decoded. The ZPI/O output graphics environment must be initialized
Format CALL SOGEND

Graphic Routines
SOGINT
Function Initialize the ZPI/O output graphics environment

COMMON/ZGSWRK/WORKSO(N)
where N is normally greater than 10,000, though it may have to be

larger depending on the number of decoded line segments. However, N
must be equal to LENWRK.
The ZPI/O and ZIGS environments must be initialized, a graphics file

opened, and a picture opened read-only before this routine is called.
Format CALL SOGINT (

1 QTXTDC , QSYMDC , QLINDC , LENWRK , IOSCAL ,
2 ISTAT )

Graphic Routines
SOGLGB
Function Obtain the next graphics feature for the picture

This subroutine retrieves the next graphics feature for the picture being
decoded.
Environment The ZPI/O output graphics environment must be initialized before this
routine is called.
Format CALL SOGLGB ( QPCEND , LGBCOD , CTRLEV , ISTAT )
Output Arguments
QPCEND L Whether end of picture is found:
.TRUE. = End of picture found
.FALSE. = There are still more graphics features
LGBCOD I Graphics feature number. (See Appendix A.

Graphics Feature Codes in the Z-MAP Plus
Reference Manual.)
CTRLEV R Contour level for contour graphics features.
1 = Error, no graphics feature on this picture

File Utilities
Introduction
Use the File Utilities subroutines to work with master files and their
member files.
Use the master file utilities to:

initialize the ZIMS environment and attach master files
open and close a master file
attach, compress, create, detach, and list master files
rename the internal name
Use the member file utilities to:

open, close, delete, list, and obtain information about member files
position a member file, then read or write records sequentially
read and write records with the member file at a random location
read, write, and set defaults for field descriptors
Internal Routines

not used by application programmers. The internal routines for file
utilities are:
SICROC Open a file with prescribed attributes or close it. Used

for creating a master file.
R2003.0 File Utilities: Introduction 169

File Management Routines
S2DELE
Function Delete a member file from a master file

This subroutine marks a member file for deletion from a master file.
The marked file is removed if the master file is compressed (as
described in SIMFCM on page 199).
this routine.
Format CALL S2DELE ( NAMZIM , MFDNZM , IHISZM , ISTAT )
170 File Utilities: Internal Routines S2DELE R2003.0

S2FLST
Function List member files

This subroutine lists member files in every master file that is attached.
The contents of the report can be restricted by file types and/or
filenames.
this routine.
Format CALL S2FLST (

1 REPORT , NAME , TYPES , BYNAME, BYTYPE ,
2 NUMTYP , LUNRPT , ISTAT )
Input Arguments
REPORT C*7 Type of report listing.
SUMMARY= List member filename, type, size
PARTIAL = List member filename, type, size, any
application program written history,
and file header
FULL = List member filename, type, size, any
application program written history,
file header, and field descriptors
NAME C*24 Prefix filename text string. Only files that have a
name starting with this prefix are listed.
TYPES C*4 Array (of length NUMTYP) containing the file
types to be listed.
BYNAME L Whether report is to be restricted by member
filename. Only files which have a prefix (or full
name) equal to the prefix filename string
(specified by NAME) are listed.
.TRUE. = Restrict listing based upon filenames
.FALSE. = Do not restrict listing based upon
filenames
BYTYPE L Whether report is to be restricted by member file

type. Only files of type TYPES are listed.
.TRUE. = Restrict listing based upon filenames
.FALSE. = Do not restrict listing based upon
filenames
NUMTYP I Number of file types to be listed.
R2003.0 File Utilities: Internal Routines S2FLST 171


LUNRPT I Logical unit for the output report file. The unit
must already be open. A zero outputs report to
unit LUNSTA specified by SIISIL (page 41).
Range Options: 099
Output Arguments
1 = No master files attached
1 = Error, invalid report type
2 = Error, invalid number of file types
3 = Error, problem creating files listing
172 File Utilities: Internal Routines S2FLST R2003.0

S2IZIM
Function Initialize the Z-MAP Information Management System (ZIMS) and

attach master files
This subroutine initializes up to four (4) master files for the file
management system and must be called before any data files can be
accessed. Each master file may contain any number of member files
which may contain control point data, grid models, fault lines, digitized
contours, well logs, etc.
To specify the number of master files assigned, do either of the
following:
Set MFDNUM to the number of master files to be attached (not
including the scratch file).
Set MFDNUM to 4 and blank-fill the unused portion of the
NAMMFD array.
This routine is equivalent to SIIZIM, but enables the user to indicate
read-only or read-write file access for the MFDs. SIIZIM assumes
read-write access only.
Environment The ZPI/O environment must be initialized before you call this routine.
Call this subroutine only once in any one application.
Format CALL S2IZIM (

1 NAMMFD , MFDNUM , IROFLG , LUNDRC , ISTAT )
Input Arguments
NAMMFD C*80 Array (of length 4) containing the name(s) of

master file(s) to be opened.
Note: These names are used only on systems
that have dynamic file allocation, but it is
good for documentation.
MFDNUM I Number of master file(s) to be attached.

Range Options: 04
IROFLG I Array (of length 4) containing a file access

indicator for each MFD.
0 = Read-write permissions
1= Read-only permissions
LUNDRC I Runtime directory physical unit number. This

variable is currently reset to 20.
Note: This variable is reserved for future use.
R2003.0 File Utilities: Internal Routines S2IZIM 173

Output Arguments
ISTAT I Default = Status flag:
1 = Warning, runtime directory is being reset
to 20
14 = Sequential number of the master file that
could not be opened
5 = Error, opening scratch file
6 = Error, opening runtime directory
7 = Error, invalid master file number
174 File Utilities: Internal Routines S2IZIM R2003.0

S2LHIS
Function List the history and ancestry of a member file

This subroutine lists the history of the file development in the order
that generations have been created, by ancestry. If the number of
generations (NUMGEN) is positive, all the generations from child
(NUMGEN=0) to the specified generation are printed. To print all
generations up to the tenth ancestry, set NUMGEN to a negative
number.
Note If IPRINT (the type of history to print) is set to zero, the routine prints
all standard invoked ZCL parameters. If set to one (1), it also prints
proposed ZCL parameters. If there is an exclamation mark (!) in the
printout, it is equivalent to a comment in ZCL. The resulting string of
commands, with minor modification, should run in ZCL.
NUMGEN = 0 Child (current)
NUMGEN = 1 Parent Parent
NUMGEN = 2 Ancestor Ancestor Ancestor Ancestor
Ancestor
Ancestor
Ancestor
Ancestor
Ancestor
Ancestor
Ancestor
Ancestor
NUMGEN = 3
this routine.
Format CALL S2LHIS (

1 NAMFIL , MFDFIL , IHSFIL , NUMGEN , LOGRPT ,
2 IPRINT , ISTAT )
R2003.0 File Utilities: Internal Routines S2LHIS 175

Input Arguments
NAMFIL C*24 Name of the file whose history is to be printed.
MFDFIL I Number of the master file containing the input
file.
Range Options: 05
IHSFIL I History display for input file:
0 = Do not display the history information
1 = Display the history information
NUMGEN I Maximum generation to display. See the note.
Set NUMGEN to a negative number to print all
information.
Range Options: 010
LOGRPT I Logical unit on which to print the report.
Default = 6
Range Options: 099
IPRINT I Type of history to print:
0 = Print standard history parameters
1 = Print standard and proposed history
parameters
Output Arguments
1 = Warning, there are no history records.
2 = Error, duplicate files. Specify master file
number.
176 File Utilities: Internal Routines S2LHIS R2003.0

S2MFAT
Function Attach a master file indicating either read-only or read-write file access
This subroutine attaches master files and reloads the runtime directory.
If at the beginning of the application there are no master files, then for
initialization purposes call the initialization routine with the number of
master files being zero and the names of the master files blanked.
This routine is equivalent to SIMFAT, but enables the user to indicate
read-only or read-write file access. SIMFAT assumes read-write
access.
this routine.
This capability is not available for nondynamic allocating systems.
Format CALL S2MFAT ( NAMMFD , IROFLG , ISTAT )
Input Arguments
NAMMFD C*80 Disk name of the master file to be attached.
IROFLG I Assigns file access permissions.
0 = Read/write access
1= Read-only access.
Output Arguments
1 = Warning, this option is unavailable for
nondynamic systems
1 = Error, master filename is blank
2 = Error, 5 master files attached already
3 = Error, master file not found
4 = Error, locked by another user
R2003.0 File Utilities: Internal Routines S2MFAT 177

S5DAFU
Function Obtain parameter, projection, and field information about a data file
This subroutine obtains information about a data file, such as file
information, parameter information, projection information, and field
descriptor information.
this routine.
Format CALL S5DAFU (

1 NAMDAT , MFDDAT , IHSDAT , NAMFLD , DEFFMT ,
2 NUMFLD , NUMWRD , NUMREC , ITYDAT , ISRTIX ,
3 IFPRJ , IPJCOD , ISPCOD , IUNCOD , IUTMCD ,
4 IHEM , IRADTY , IFDTYP , IFDINX , IFDWRD ,
5 IFDSRT , ROTANG , SEPMRK , CTRINT , BOTPAR ,
7 FNORTH , FEAST , UNTFAC , AXISA , AXISB ,
8 AZMTH , SCALE , FDZNON , XMIN , XMAX ,
9 YMIN , YMAX , ISTAT )
Input Arguments
NAMDAT C*24 Name of the input data file.

MFDDAT I Number of the master file that contains the input
data file.
Range Options: 05
IHSDAT I History display for input file:
Output Arguments
NAMFLD C*20 Array of the files field names (of length 50).
DEFFMT C*6 Array of default field output formats (length 50)
NUMFLD I Number of fields on the file.
NUMWRDI Number of words per data record on the file.
NUMREC I Number of records on the file.
ITYDAT I Type of data on input file. 1 = grid, 2 = data, 3 =

contour, etc. (See Appendix B. File and Field
178 File Utilities: Internal Routines S5DAFU R2003.0


ISRTIX I Primary file sort index.
IFPRJ I Type of projection information:
1 = No projection information
2 = Projection information
3 = Projected but no information
PJCOD * I Cartographic projection:

16 = Grads and Bipolar Oblique Conic Conformal
10 = Grads and Albers Equal Area (equivalent)
with two standard parallels
9 = Grads and Modified Rectangular Orthotomic
Polyconic
standard parallels
standard parallel
1 = Degrees and Universal Transverse Mercator
2 = Degrees & General Transverse Mercator
standard parallel
standard parallels
10= Degrees and Albers Equal Area equivalent
with two standard parallels
13 = Degrees and Oblique Mercator
15= Degrees and Cassini-Soldner
Conformal
R2003.0 File Utilities: Internal Routines S5DAFU 179



1 = User defined
2 = Everest 1830
4 = Bessel 1841
5 = Airy 1858
6 = Clarke 1858
7 = Clarke 1866
8 = Clarke 1880
9 = Hayford 1909
11 = Hough 1956
13 = Kaula 1961
16 = WGS-72 1972
17 = IUGG 1975
18 = Helmert
19 = Ghana National
20 = WGS-84 (GRS-80)
IUNCOD I Units for projected coordinates:

* 1 = User defined
2 = Meters
3 = Feet
4 = Yards
5 = Inches
6 = Kilometers
7 = Nautical miles
8 = Statute miles
9 = U S Survey feet

Reference Manual.)
IHEM * I Which hemisphere:

0 = Cannot be determined
1 = Northern
2 = Southern
IFDTYP I Array (of length 100) containing the field type

codes.
IFDINX I Array (of length 100) containing the index of the

first word for each field.


IFDWRD I Array (of length 100) containing the number of

words for each field.
IFDSRT I Array (of length 100) containing the secondary sort

index for each field.
ROTANG R Rotation angle for the file.
SEPMRK R Separator or marker value for contour, seismic or

cross-section files.
CTRINT R Contour equal interval value. Zero if the contour

intervals are unequal.
BOTPAR R Standard parallel closest to the equator (least), in

* degrees.
TOPPAR R Standard parallel closest to pole (greatest), in
* degrees.
REFLAT R Reference latitude.

*
SFLAT * R Scale factor for the reference latitude.
REFLON R Reference longitude.

*
SFLON * R Scale factor for the reference longitude.

*
UNTFAC R Projection coordinates units factor.

*
AXISA * R Semimajor axis, if spheroid is user-defined

(ISPCOD = 1).
AXISB * R Semiminor axis, if spheroid is user-defined

(ISPCOD = 1).
FDZNON R Array (of length 100) containing the null (ZNON)

values for the fields.


XMIN D Minimum x coordinate for the file.
XMAX D Maximum x coordinate for the file.
YMIN D Minimum y coordinate for the file.
YMAX D Maximum y coordinate for the file.

1 = Error, invalid master file number or master
file is read-only.
2 = Error, duplicate files. Specify master file
number.
5 = Error, this is a grid file not a data file.

Checklist for Projection Arguments vs. Projection Type

Projection Type



Azimuthal Gnomonic
American Polyconic
Modified Polyconic
Albers Equal Area
Standard Mercator
Van Der Grinten I

Cassini-Soldner
Arguments
Name Description
1
Key:
1
2
3
* User defined

SIDFFD
Function Set default field descriptors

This subroutine sets defaults for a field descriptor or allows the
application program to override those defaults of interest. This
subroutine should be used in conjunction with writing a field
descriptor.
Environment The ZPI/O and ZIMS environments must be initialized and a file
opened before you call this routine.
Format CALL SIDFFD (

1 NAMFLD , IFDFMT , IFDTYP , IFDWID , IFDDEC ,
2 INXFLD , IFDWDS , IFDSRT , ZNON , ZALMIN ,
3 ZALMAX , VECTOR , ISTAT )
Input Arguments
NAMFLD C*20 Field name. Blanked if the default name based

on the field type (IFDTYP) is to be used.
IFDFMT C*1 Output format type.

Default = for CHARACTER, A or
for REAL, G
Range Options: A, I, F, E, G
IFDTYP I Field type. (See Appendix B. File and Field

IFDWID I Field width. It is recalculated if the number of

decimals and the field width are not compatible.
Default = for CHARACTER, HOL *
IFDWDS
or for REAL, 15
IFDDEC I Number of decimals for the field.

Default = for INTEGER, 0
INXFLD I Index of first word for field in each record.
IFDWDS I Number of words for field.

Default = 1
IFDSRT I Sort field index.

Default = 0
184 File Utilities: Internal Routines SIDFFD R2003.0


ZALMIN R Minimum allowed z value.
ZALMAX R Maximum allowed z value. Reset to 1E30 if the

minimum and maximum allowed values are the
same.
Output Arguments
VECTOR R Array (of length 20) containing the following
information:
15 = Field name
6 = Field type
7 = Field output format type
8 = Field width
9 = Number of decimals for the field
10 = Index of the fields first word
11 = Number of words for the field
13 = Null value
14 = Minimum allowed z value
15 = Maximum allowed z value
20 = Sort field index
R2003.0 File Utilities: Internal Routines SIDFFD 185


9 = Warning, maximum value allowed was
less than or equal to minimum value
allowed, it was reset to 1E30.
8 = Warning, the number of words was reset
to 1.
7 = Warning, the width of the field is not large
enough for the format type, it has been
adjusted.
6 = Warning, the width of the field was zero
and has been reset to 15.
5 = Warning, output type was integer, number
of decimals was not zero, it has been reset
to 0.
4 = Warning, not a valid format type, has been
reset to G.
3 = Warning, format type was blank, has been
reset to G.
2 = Warning, the number of words was zero,
has been reset to one.
1 = Warning, field type does not have a
known field name. The field name has
been set to DATA FIELD.
1 = Error, index of first word for field was
zero.
186 File Utilities: Internal Routines SIDFFD R2003.0

SIDNFL
Function Retrieve information about a member file from the runtime directory
This subroutine takes the index number in the runtime directory for the
file and returns the name, type, and master file number for that file.
this routine.
Format CALL SIDNFL (

1 NFILE , INXFIL , NAMZIM , FILTYP , MFDNZM ,
2 NUMFIL , ISTAT )
Input Arguments
NFILE I Number of files to be obtained.
Range Options: >0
INXFIL I Array (of length NFILE) containing the indices
of the files for which information is to be
obtained. Set INXFIL(1) = NFILE or a large
negative number to obtain all files.
Output Arguments
NAMZIM C*24 Array (of length NFILE) containing the name of

each member file.
FILTYP C*4 Array (of length NFILE) containing the file type
for each member file, e.g., grid, data, etc.
MFDNZM I Array (of length NFILE) containing the number

of the master file for each member file.
NUMFIL I Number of files for which information was

actually obtained.

1 = Warning, file has been deleted
1 = Error, invalid index
2 = Error, end-of-file on runtime directory
reached
3 = Error, index is out of range
R2003.0 File Utilities: Internal Routines SIDNFL 187

SIEZIM
Function Close master files

This subroutine closes the Z-MAP Information Management System
master files. On Unix systems (which use lock files to limit access to
master files) this routine removes the lock files. You can call this
routine on other systems that do not use lock files, but it is
unnecessary.
Call this routine during exit processing for any programs that use
master files. Call SIEZIM in such a way that normal and error exits call
SIEZIM.
this routine.
Format CALL SIEZIM
188 File Utilities: Internal Routines SIEZIM R2003.0

SIFCLO
Function Close a member file

This subroutine closes a dataset in a master file.
Only five (5) datasets may be open at a time. Once that limit is reached,
you must close a member file in order to open another one.
Format CALL SIFCLO ( LOGFIL , ISTAT )
Input Arguments
LOGFIL I Logical file code for the member file to be
closed.
Range Options: 15
Output Arguments
1 = Error, problem closing file
R2003.0 File Utilities: Internal Routines SIFCLO 189

SIFLDR
Function Read a field descriptor

This subroutine reads field descriptor values from a member file. The
arguments IFMT, IFWID, and IDEC are used to synthesize
FORTRAN format statements when reports are printed.
Environment The ZPI/O and ZIMS environments must be initialized and the
member file opened before you call this routine.
Format CALL SIFLDR (

1 LOGFIL , NUMFLD , FLDNAM , IFMT , ITYPE ,
2 NWORDS , INDEX , IFWID , IDEC , NXSORT ,
3 ZNON , FMIN , FMAX , ISTAT )
Input Arguments
LOGFIL I Logical file code to access the file.
Range Options: 15
NUMFLD I Number of field descriptor to be read.
Output Arguments
FLDNAM C*20 Field name.
IFMT C*1 Output conversion type.

Range Options: A, I, F, E, or G
ITYPE I Type of field. (See Appendix B. File and Field

NWORDS I Number of words in field.
INDEX I Position (word number) in the record where the

data for this field starts.
IFWID I Field width (characters) for output.
IDEC I Number of significant digits right of the decimal

for output.
190 File Utilities: Internal Routines SIFLDR R2003.0


NXSORT I Index of next sort field (linked list):

0 = None
FMIN R Minimum allowed field value. Can be zero.
FMAX R Maximum allowed field value. Can be zero.

1 = Error, reading direct access file
2 = Error, field number does not exist
R2003.0 File Utilities: Internal Routines SIFLDR 191

SIFLDW
Function Write a field descriptor

This subroutine writes a field descriptor for a new file. The arguments
IFMT, IFWID, and IDEC are used to synthesize FORTRAN Format
statements when reports are printed. IFMT indicates type of data in the
field. For alphanumeric fields, IFWID is the length of the string
(number of characters) and IDEC is ignored.
If the file has more than 24 fields, the field descriptors should be
written before any data is written. You can use dummy information to
write field descriptors and update the descriptors after you write the
data.
Format CALL SIFLDW (

1 FLDNAM , IFMT , LOGFIL , NUMFLD , ITYPE ,
2 NWORDS , INDEX , IFWID , IDEC , NXSORT ,
3 ZNON , FMIN , FMAX , ISTAT )
Input Arguments
FLDNAM C*20 Field name.
IFMT C*1 Output conversion type.
Range Options: A,I,F,E or G
Range Options: 15
NUMFLD I Number of the field descriptor to be written.
ITYPE I Type of field. (See Appendix B. File and Field
NWORDS I Number of words in field.
INDEX I Position (word number) in the record where data
for this field starts.
IFWID I Field width (characters) for output.
IDEC I Number of significant digits to the right of
decimal for output.
192 File Utilities: Internal Routines SIFLDW R2003.0


NXSORT I Index of next sort field (linked list):
0 = None
FMIN R Minimum allowed field value.
FMAX R Maximum allowed field value.
Output Arguments
1 = Error, writing direct access file
R2003.0 File Utilities: Internal Routines SIFLDW 193

SIFRED
Function Read a record from a member file

This subroutine reads a record from a file. The record length is
determined from the parameter record for the file. For data files, it is
NWORDS when calling the read data parameter information routine
SIPRRD. For grid files, data is stored in column order so that the
record length is specified in NROWS when calling the read grid
parameter information routine SIPRRG.
Note IREC has a special capability. If a number of sequential reads are to be

performed after positioning the file, perform the following steps:
1. Set IREC equal to the first record to be read, then call this routine.
2. Set IREC = 0 for the remaining number of sequential reads.
Format CALL SIFRED (

1 LOGFIL , IREC , NWRDS , IWORD , DATA ,
2 ISTAT )
Input Arguments
Range Options: 15
IREC I Record number to read. If IREC = 0, the next
sequential record is read. See the note above.
NWRDS I Number of words to read, usually the record
length.
Output Arguments
IWORD I Number of sequential words left to read.
DATA R Array (of length NWRDS) containing the data
(the data record read from the file).
1 = Error, positioning file
2 = Error, file error
3 = Error, end of file detected while
positioning file
4 = Error, number of words to read is zero
194 File Utilities: Internal Routines SIFRED R2003.0

SIFWRT
Function Write a record to a member file

This subroutine writes a record to a file. Record length is determined
from the parameter record for the file. For data files, it is NWORDS
when calling the write data parameter information routine SIPRWD.
For grid files, data is stored in column order so that the record length is
specified in NROWS when calling the write grid parameter
information routine SIPRWG.
Note IREC has a special capability. If a number of sequential writes are to be

performed after positioning the file, follow these steps:
1. Set IREC equal to the first record to be written, call this routine.
2. Set IREC = 0 for the remaining number of sequential writes.
Environment If this routine is used for random access I/O, the record to be written
must already exist on the file. This routine cannot extend a file except
through sequential writes.
Format CALL SIFWRT (

1 LOGFIL , IREC , NWRDS , DATA , IWORD ,
2 ISTAT )
Input Arguments
LOGFIL I Logical file code to access file.

Range Options: 15
IREC I Record number to write. If IREC = 0, the next

sequential record is written. See the note above.
NWRDS I Number of words to write, usually the record

length.
DATA R Array (of length NWRDS) containing the data to

be written.
R2003.0 File Utilities: Internal Routines SIFWRT 195

Output Arguments
IWORD I Total number of words written sequentially, if

IREC = 0.

2 = Error, writing to file
3 = Error, number of words to write is zero
196 File Utilities: Internal Routines SIFWRT R2003.0

SIIZIM
Function Initialize the Z-MAP Information Management System (ZIMS) and

attach master files
This subroutine initializes up to four (4) master files for the file
management system and must be called before any data files can be
accessed. Each master file may contain any number of member files
which may contain control point data, grid models, fault lines, digitized
contours, well logs, etc.
To specify the number of master files assigned, do either of the
following:
Set MFDNUM to the number of master files to be attached (not
including the scratch file).
Set MFDNUM to 4 and blank-fill the unused portion of the
NAMMFD array.
This subroutine should be called only once in any one application.
Format CALL SIIZIM (

1 NAMMFD , MFDNUM , LUNDRC , ISTAT )
Input Arguments
NAMMFD C*80 Array (of length 4) containing the name(s) of

master file(s) to be opened.
Note: These names are used only on systems
with dynamic file allocation, but it is
good for documentation.
MFDNUM I Number of master file(s) to be attached.

Range Options: 04
LUNDRC I Runtime directory physical unit number. This

variable is currently reset to 20.
Note: This variable is reserved for future use.
Output Arguments
1 = Warning, runtime directory is reset to 20
14 = Sequential number of the master file that
could not be opened
5 = Error, opening scratch file
6 = Error, opening runtime directory
R2003.0 File Utilities: Internal Routines SIIZIM 197

SIMFAT
Function Attach a master file
This subroutine attaches master files and reloads the runtime directory.
Note The following example shows how the current master file maintenance
structure stores the location (logical units) of the master files:
Routine SIIZIM SIMFAT SIMFDT SIMFAT SIMFDT
Process Initialize Attach Detach Attach Detach
ZIMS with Third Second Fourth All
2 MFDs MFD MFD MFD MFDs
Result 1 = MFD 1 1 = MFD 1 1 = MFD 1 1 = MFD 1 1 = Scratch
2 = MFD 2 2 = MFD 2 2 = 2 = MFD 4 2 =
3 = Scratch 3 = Scratch 3 = Scratch 3 = Scratch 3 =
4 = 4 = MFD 3 4 = MFD 3 4 = MFD 3 4 =
5 = 5 = 5 = 5 = 5 =
this routine. This capability is not available for nondynamic allocating
systems.
Format CALL SIMFAT ( NAMMFD , ISTAT )
Input Arguments
NAMMFD C*80 Disk name of the master file to be attached.
Output Arguments
nondynamic systems
2 = Error, 5 master files attached already
3 = Error, master file not found
198 File Utilities: Internal Routines SIMFAT R2003.0

SIMFCM
Function Compress a master file
This subroutine copies the files from one master file into another
master file, removing files that were marked for deletion.
this routine.
Format CALL SICPMF ( LUNCFM , LUNCTO , NUMCPY , ISTAT )
Input Arguments
LUNCFM I Logical unit of master file to copy files from.
Range Options: 15
LUNCTO I Logical unit of master file to copy files into.
Range Options: 15
Output Arguments
NUMCPY I Number of member files copied.
1 = Error, problem compressing master file
R2003.0 File Utilities: Internal Routines SIMFCM 199

SIMFCR
Function Create a new master file

This subroutine creates a new empty master file.
Format CALL SIMFCR (

1 NAMMFD , INTMFD , MFDLUN , ISTAT )
Input Arguments
NAMMFD C*80 Disk name of the new master file, fully

qualified.
This name is not used on systems that do not
have dynamic file allocation, but it is good for
documentation.
INTMFD C*24 Internal name of master file, which appears

when files are listed. If INTMFD is blank, the
first 24 characters of NAMMFD are used.
MFDLUN I Logical unit on which to create the master file.

Note: If other master files have been attached
by either SIIZIM or SIMFAT, some of
the logical units have been used up. For
example:
If ZIMS was initialized with
NUMMFD = 0 (See SIIZIM on
page 197.) The first master file
attached is the scratch file. It is
attached to logical unit 21.
If a second master file is then attached.
(See SIMFAT on page 198.) This
second master file is assigned to
logical unit 22.
If you then create a master file
(SIMFCR), you may do so on logical
unit 23, 24, or 25, but not on 21 or 22,
since they are already allocated.
Range Options: 2125
200 File Utilities: Internal Routines SIMFCR R2003.0

Output Arguments
2 = Error, master file FORTRAN unit is zero
3 = Error, opening FORTRAN file
4 = Error, writing to file
R2003.0 File Utilities: Internal Routines SIMFCR 201

SIMFDT
Function Detach one or all master files

This subroutine detaches master files and reloads the runtime directory.
Note The following example shows how the current master file maintenance
structure stores the location (logical units) of the master files:
Routine SIIZIM SIMFAT SIMFDT SIMFAT SIMFDT
Process Initialize Attach Detach Attach Detach
ZIMS with Third Second Fourth All
2 MFDs MFD MFD MFD MFDs
Result 1 = MFD 1 1 = MFD 1 1 = MFD 1 1 = MFD 1 1 = Scratch
2 = MFD 2 2 = MFD 2 2 = 2 = MFD 4 2 =
3 = Scratch 3 = Scratch 3 = Scratch 3 = Scratch 3 =
4 = 4 = MFD 3 4 = MFD 3 4 = MFD 3 4 =
5 = 5 = 5 = 5 = 5 =
this routine.
This capability is not available for nondynamic allocating systems.
Format CALL SIMFDT ( NAMMFD , ISTAT )
Input Arguments
NAMMFD C*80 Disk name of master file to detach. Blanked if all
master files, including the scratch file, are to be
detached. A new blank scratch file is attached.
The disk name for the scratch file is Scratch
File.
Output Arguments
nondynamic systems
1 = Error, problem reinitializing ZIMS
2 = Error, no match for the disk master file
202 File Utilities: Internal Routines SIMFDT R2003.0

SIMFLS
Function List attached master files

This subroutine reads the attached master files and provides a listing of
the disk names, the internal names, the number of records, and the
number of records used.
this routine.
Format CALL SIMFLS (

1 NAMMFD , NAMINT , MFDNUM , NUMREC, NUMUSE ,
2 ISTAT )
Output Arguments
NAMMFD C*80 Array (of length 5) containing the disk names of
the attached master files.
NAMINT C*24 Array (of length 5) containing the internal names
of the attached master files.
MFDNUM I Number of master files attached.
NUMREC I Array (of length 5) containing the number of
records on the master file.
NUMUSE I Array (of length 5) containing the number of
records used.
1 = Warning, no master files attached
R2003.0 File Utilities: Internal Routines SIMFLS 203

SIMFRN
Function Rename the internal name of a master file

This subroutine replaces the internal name of a master file with a new
name.
You can use SIMFLS to list internal names.
appropriate master file attached before you call this routine.
Format CALL SIMFRN ( NAMMFD , NAMINT , ISTAT )
Input Arguments
NAMMFD C*80 Disk name of the master file.
NAMINT C*24 New internal name of the master file.
Output Arguments
1 = Error, the disk or internal master file
name is blank
2 = Error, the disk master file cannot be found
3 = Error, problem reading/writing internal
master file name
204 File Utilities: Internal Routines SIMFRN R2003.0

SINOPN
Function Open a new member file

If there are no duplicate files, NAMRET is identical to NAMZIM.
If there are duplicate files, characters 2124 of NAMRET contain the
version number.
this routine.
Format CALL SINOPN (

1 NAMZIM , INWTYP , MFDNZM , NAMRET , LOGFIL ,
2 ISTAT )
Input Arguments
NAMZIM C*24 Name of new member file. See the note above.
INWTYP C*4 Type of new member file. (See Appendix B.

File and Field Codes in the Z-MAP Plus
Reference Manual.)
MFDNZM I Number of the master file to contain the new

member file. A zero or the appropriate master
file number may be used to point to the scratch
master file.
Range Options: 05
Output Arguments
NAMRET C*24 Name of new member file, with version number
added if there were duplicate files.
LOGFIL I Logical file code for the new member file.
Range Options: 15
1 = Warning, duplicate files. A version
number has been added.
2 = Error, invalid version number.
R2003.0 File Utilities: Internal Routines SINOPN 205

SIOOPN
Function Open an old member file
this routine.
Format CALL SIOOPN (

1 NAMZIM , MFDNZM , IHISZM , IOLTYP , LOGFIL ,
2 ISTAT )
Input Arguments
NAMZIM C*24 Name of old member file.
MFDNZM I Number of the master file containing the
member file. A zero or the appropriate master
file number can be used to search for the file.
Range Options: 05
IHISZM I History display for input file:
Output Arguments
IOLTYP C*4 Type of old member file. (See Appendix B. File
and Field Codes in the Z-MAP Plus Reference
Manual.)
LOGFIL I Logical file code for the old member file.
Range Options: 15
2 = Error, duplicate files
206 File Utilities: Internal Routines SIOOPN R2003.0

SIPRRC
Function Read a general data or contour parameter record

This subroutine retrieves the parameter record for the general data or
contour file connected to LOGFIL.
member file must be opened before you call this routine.
Format CALL SIPRRC (

1 LOGFIL , NFLDS , NWORDS , NRECS , ICNTSP ,
2 ISORTF , XMIN , XMAX , YMIN , YMAX ,
3 ZNON , VALMRK , CNTINC , ROTANG , ISTAT )
Input Arguments
Range Options: 15
Output Arguments
NFLDS I Number of data fields on the file.
NWORDS I Number of words on each data record.
NRECS I Number of data records in the file.
ICNTSP I Type of contour interval spacing. Needed only if

file is a contour file:
0 = Not needed
1 = Equally spaced contour intervals
2 = Unequally spaced contour intervals
3 = Unknown spacing of contour intervals
ISORTF I Index of primary sort field:

0 = None
XMIN D Minimum x coordinate for this file.
XMAX D Maximum x coordinate for this file.
YMIN D Minimum y coordinate for this file.
YMAX D Maximum y coordinate for this file.
R2003.0 File Utilities: Internal Routines SIPRRC 207


ZNON R Null data value for the file.
VALMRK R Marker value for contour, cross-section or

seismic section files.
CNTINC R Contour increment for equally spaced contour

intervals (ICNTSP = 1).
ROTANG R Angle if the file has been rotated.

208 File Utilities: Internal Routines SIPRRC R2003.0

SIPRRD
Function Read a data parameter record

This subroutine retrieves the parameter record for the data file
connected to LOGFIL.
Format CALL SIPRRD (

1 LOGFIL , NFLDS , NWORDS , NRECS , ISORTF ,
2 XMIN , XMAX , YMIN , YMAX , ZNON ,
3 ISTAT )
Input Arguments
Range Options: 15
Output Arguments
NFLDS I Number of data fields on the file.
0 = None
ZNON R Null data value for the file.
R2003.0 File Utilities: Internal Routines SIPRRD 209

SIPRRG
Function Read a grid parameter record

This subroutine retrieves the parameter headers for the grid file
referenced by LOGFIL.
Format CALL SIPRRG (

1 LOGFIL , NROWS , NCOLS , XMIN , XMAX ,
2 YMIN , YMAX , GXINC , GYINC , ZNON ,
3 GMAX , GMIN , ISTAT )
Input Arguments
Range Options: 15
Output Arguments
NROWS I Number of grid rows (record length).
NCOLS I Number of grid columns (file length), in records.
XMIN D Minimum x coordinate for this grid.
XMAX D Maximum x coordinate for this grid.
YMIN D Minimum y coordinate for this grid.
YMAX D Maximum y coordinate for this grid.
GXINC R Grid increment in the x direction.
GYINC R Grid increment in the y direction.
ZNON R Null data value for file.
GMAX R Maximum grid z value.
GMIN R Minimum grid z value.

210 File Utilities: Internal Routines SIPRRG R2003.0

SIPRWC
Function Write a general data or contour parameter record

This subroutine writes information to the parameter record for the
general data or contour file referenced by LOGFIL. This record should
be written after the last record of the data has been written, to give the
program the opportunity to calculate correct values for NRECS,
XMIN, XMAX, YMIN, and YMAX.
Format CALL SIPRWD (

1 LOGFIL , NFLDS , NWORDS , NRECS , ICNTSP ,
2 ISORTF , XMIN , XMAX , YMIN , YMAX ,
3 ZNON , VALMRK , CNTINC , ROTANG , ISTAT )
Input Arguments

Range Options: 1- 5
NFLDS I Number of data fields in the file.
ICNTSP I Type of contour interval spacing. Needed only if

file is a contour file.
0 = Not needed
1 = Equally spaced contour intervals
2 = Unequally spaced contour intervals
3 = Unknown spacing of contour intervals

0 = None
R2003.0 File Utilities: Internal Routines SIPRWC 211


VALMRK R Marker value for contour, cross-section, or

seismic section files.
CNTINC R Contour increment for equally spaced contour

intervals. Needed if ICNTSP = 1.
ROTANG R Angle of the file rotation.
Output Arguments
212 File Utilities: Internal Routines SIPRWC R2003.0

SIPRWD
Function Write a data parameter record

This subroutine writes information to the parameter record for the data
file referenced by LOGFIL. This record should be written after the last
record of the data has been written, to give the program the opportunity
to calculate correct values for NRECS, XMIN, XMAX, YMIN, and
YMAX.
Format CALL SIPRWD (

1 LOGFIL , NFLDS , NWORDS , NRECS , ISORTF ,
2 XMIN , XMAX , YMIN , YMAX , ZNON ,
3 ISTAT )
Input Arguments

Range Options: 1- 5
NFLDS I Number of data fields in the file.

0 = None
Output Arguments
R2003.0 File Utilities: Internal Routines SIPRWD 213

SIPRWG
Function Write a grid parameter record

This subroutine writes information to the parameter record for the grid
file referenced by LOGFIL.
Format CALL SIPRWG (

1 LOGFIL , NROWS , NCOLS , XMIN , XMAX ,
2 YMIN , YMAX , GXINC , GYINC , ZNON ,
3 GMAX , GMIN , ISTAT )
Input Arguments

Range Options: 15
NROWS I Number of grid rows (record length).
NCOLS I Number of grid columns (file length) in records.
XMIN D Minimum x coordinate for this grid.
XMAX D Maximum x coordinate for this grid.
YMIN D Minimum y coordinate for this grid.
YMAX D Maximum y coordinate for this grid.
GXINC R Grid increment in the x direction.
GYINC R Grid increment in the y direction.
GMAX R Maximum grid z value.
GMIN R Minimum grid z value.
Output Arguments
214 File Utilities: Internal Routines SIPRWG R2003.0

SIRDPO
Function Position a member file for a sequential read

To read additional information from the file, call the sequential read
routine, SIRDSQ (page 217).
Format CALL SIRDPO ( LOGFIL , IWORD , ISTAT )
Input Arguments
Range Options: 15
IWORD I Word number to position file to.
Output Arguments
1 = Warning, end of file
1 = Error, invalid member file unit
2 = Error, invalid word position
R2003.0 File Utilities: Internal Routines SIRDPO 215

SIRDRN
Function Read from a member file at a random location

This subroutine reads the requested number of words from a member
file starting at the position that is input, this is a word position. The
concept of records that are a certain number of words long is kept at
user level and is not intrinsic to the routine. It simply does word
operations.
Format CALL SIRDRN (

1 LOGFIL , IWORD , NWORDS , ARRAY , ISTAT )
Input Arguments
Range Options: 15
IWORD I Word location at which to start reading.
NWORDS I Number of words to be read.
Output Arguments
ARRAY R Array (of length NWORDS) containing data that
was read.
1 = Error, invalid file unit
3 = Error, number of words to read is zero
4 = Error, reading file
216 File Utilities: Internal Routines SIRDRN R2003.0

SIRDSQ
Function Read from a member file sequentially

Position the file for a sequential read before you call this routine (as
described in SIRDPO on page 215).
Format CALL SIRDSQ (

1 LOGFIL , NWORDS , IEOF , ARRAY , ISTAT )
Input Arguments
Range Options: 15
NWORDS I Number of words to be read.
Output Arguments
IEOF I End of file:
0 = This record is not the last one
1 = End of file (EOF) reached. This record is
the last one.
ARRAY R Array (of length NWORDS) containing data that
is read.
1 = Error, invalid member file unit.
2 = Error, number of words to read is zero.
3 = Error, reading file.
R2003.0 File Utilities: Internal Routines SIRDSQ 217

SIRHIS
Function Read history information from a member file

This subroutine reads a single record of history information or all of
the history for a particular member file.
Format CALL SIRHIS (

1 LOGFIL , IHREC , INFHIS , NOHREC , ISTAT )
Input Arguments
Range Options: 15
IHREC I Number of the history record to be retrieved or
zero for all history records.
Output Arguments
INFHIS C*80 Array (of length 20) containing the requested

history information.
NOHREC I Number of history records on the file.

1 = Error, old (pre-1985) format history
record, cannot be read
2 = Error, no history records on the file
3 = Error, history record requested does not
exist
218 File Utilities: Internal Routines SIRHIS R2003.0

SIWHIS
Function Write history records to a member file

This subroutine allows the application programs to write NORECS
history records of 80 byte character strings to a known member file.
Each file may contain up to 20 history records.
Format CALL SIWHIS (

1 INFHIS , NORECS , LOGFIL , NTHREC , ISTAT )
Input Arguments
INFHIS C*80 Array (of length NORECS) containing the
history information.
NORECS I Number of records to be written.
Range Options: 120
LOGFIL I Logical file code to access member file.
Range Options: 15
Output Arguments
NTHREC I Total number of history records on the member
file.
1 = Error, record number invalid
2 = Error, writing the history information
R2003.0 File Utilities: Internal Routines SIWHIS 219

SIWRPO
Function Position a member file for a sequential write

To write additional information to the file, call the sequential write
routine, SIWRSQ (page 222).
Format CALL SIWRPO ( LOGFIL , IWORD , ISTAT )
Input Arguments
Range Options: 15
IWORD I Word number at which to position the file.
Output Arguments
1 = Error, invalid member file unit
220 File Utilities: Internal Routines SIWRPO R2003.0

SIWRRN
Function Write to a member file at a random location

This subroutine writes to a file at a random location. If the file needs to
be expanded, use the sequential write routine, preceded by positioning
the file for a sequential write.
Data may be overwritten if care is not taken in positioning the file.
Format CALL SIWRRN (

1 LOGFIL , IWORD , NWORDS , ARRAY , ISTAT )
Input Arguments
Range Options: 15
IWORD I Word location at which to start writing.
NWORDS I Number of words to be written.
ARRAY R Array (of length NWORDS) containing the data
to be written.
Output Arguments
1 = Error, invalid member file number
4 = Error, writing file
R2003.0 File Utilities: Internal Routines SIWRRN 221

SIWRSQ
Function Write to a member file sequentially

This subroutine writes to a member file sequentially. This routine is
used for expanding a files length. The random write routine cannot be
used for this purpose.
The file should be positioned for a sequential write before you call this
routine (as described in SIWRPO on page 220).
Data may be overwritten if care is not taken in positioning the file.
Format CALL SIWRSQ ( LOGFIL , NWORDS , ARRAY , ISTAT )
Input Arguments
Range Options: 15
NWORDS I Number of words to be written.
ARRAY R Array (of length NWORDS) containing the data
to be written.
Output Arguments
1 = Error, invalid member logical file
3 = Error, writing file
222 File Utilities R2003.0

Appendix A.
ZIGS Overview
Introduction
The Z-MAP Interactive Graphics System (ZIGS) is a comprehensive
graphics software package that operates with a broad range of graphics
peripherals. As a ZPI/O programmer, you will be most concerned with
placing graphics into or extracting graphics from a Z-MAP Graphics
File (ZGF). This file contains graphics in a packed form and, like a
metafile, is device independent. Many of the routines in the Graphics
Utilities section are involved with ZIGS operations.
This appendix is an introduction to ZIGS for the new ZPI/O

programmer and a ZIGS reference for the more experienced ZPI/O
programmer. The next topic describes the ZIGS file structure, followed
by a topic describing step-by-step how to write and read a picture in a
ZIGS graphics file.
ZIGS File Structure

The basic ZIGS file structure is the Z-MAP Graphics File (ZGF), a
direct access binary file with fixed record length. Each ZGF is a
collection of independent pictures. The number of pictures which can
be written to a particular ZGF is limited only by the number of records
allocated to that ZGF. The limitation is normally a very large number
(like 600,000 records) so the usual limitation is running out of space on
the disk where the ZGF resides.
Picture Components
Each picture is composed of a set of graphics segment types (e.g.,
contours, borders, cross-section lines, lithology columns, etc.) which
are often called logical graphics blocks (LGBs) or graphics features.
An LGB (graphics feature) is therefore a marker identifying some
specific type of graphic data.
Contours, posted well data, title block components, seismic lines and
other features can also be grouped together in a single LGB.
223 Appendix A. ZIGS Overview R2003.0

All types of LGBs used in ZPI/O can be broken down into four groups
of graphic primitives: lines, text, symbols and polygons. Any number
of primitives can be written to an LGB, but picture editing is less
efficient if massive amounts of graphics are created in a single LGB. A
list of allowed LGB types can be found in Appendix A. Graphics
Feature Codes in the Z-MAP Plus Reference Manual.
A copy of the color table assigned to the logical name ZYCOLOR is

attached to each picture. By assigning different tables to the logical
name in different runs, you can change the color table from picture to
picture. Different pictures on the same ZGF can have different color
tables. The color index used in many ZPI/O routines is a reference to
this color table. If no specific index is assigned, the default index
assigned in the Color Index section of the table is used to define the
color of the primitive. The Color Representation section defines the
color used for each index. (See Appendix F. Color Editing in the
Headers
Each ZGF, picture and LGB has a header which stores pertinent
information. The ZGF header contains file identification text, file status
information, the number of records allocated to the file, and a pointer to
the next unused record.
The picture header contains the name of the picture, status information,
a pointer to the first LGB header in that picture, the location of the next
picture header, and the display parameters which define the scale and
area of the plot.
Each LGB header contains a pointer to a sequential list of graphic

primitives. The LGB header begins with a unique three-integer name
for the LGB. The first word identifies the type of LGB, the second
word indicates the number of LGBs of this type already created and the
third word indicates the number of modifications made to the LGB. As
a picture is edited, new versions of an LGB are created. These versions
have the same name as the original LGB, but the version number is
changed.
Also included in the LGB header are pointers to the actual primitive
data, connections to both previous and later versions of the LGB, a
display priority number and the coordinates of the minimum enclosing
box around the LGB with lines parallel to the x and y axes.
R2003.0 Appendix A. ZIGS Overview 224

ZGF Header
Header Picture 1
LGB 1
Primitive 1
Primitive 2
Primitive n
LGB 2
Primitive 1
Primitive 2
Primitive m
LGB K
Header Picture z
ZIGS File Structure

ZIGS Programmers Guide

This section is a tutorial about using ZIGS in ZPI/O application
programs. The first topic describes placing graphics into a ZGF. The
second topic describes extracting graphics from a ZGF.
Input Graphics to a Picture

The general procedure for placing graphics into a picture is:
1. Initialize the ZPI/O environment.
2. Initialize the ZIGS environment.
3. Initialize a ZGF graphics file.
4. Initialize a picture.
5. Initialize a graphics feature (LGB).
6. Set LGB attributes.
7. Write graphics primitives to the picture.
8. Close the LGB.
9. Close the picture.
10. Close the ZGF.
11. Close the ZIGS environment.
12. Close the ZPI/O environment.
The steps for placing graphics into a picture are:

1. Initialize ZPI/O environment.
Call SICOMM or SIISIL to initialize the common blocks, logical
units, etc., used in the entire ZPI/O system. SICOMM enables you
to set IDBUG to print or not print debug messages and to set the
length of the workspace, sending output messages to the default
logical unit, 6. SIISIL sets the IDBUG flag, the workspace length,
and the logical unit for five types of output messages.
Warning Call SICOMM or SIISIL First
If SICOMM or SIISIL is not the first ZPI/O routine called, you could get
serious errors and many types of errors when you call other ZPI/O routines.

C
C
C


Call SIIZIG to initialize the ZIGS environment. This routine
initializes common blocks used only by ZIGS and opens and reads
the default color table into the system.
C
CALL SIIZIG
C
3. Initialize a graphics file.

Call SIIZGF to create and initialize a Z-MAP Graphics File (ZGF)
on which to store the graphics information generated. If the ZGF
already exists, the routine initializes and opens the file.
C
ZGFNAM = /disk/directory/my.zgf
NEWZGF = NEW
C
Call S3IPIC to open either a new or an old 2D (baseplane) picture.
If the picture is new, input arguments must include the picture
name, projection information, information on the Area of Interest
(AOI) to be mapped and scaling information. If the picture is an
old one (it has been previously created), you must only supply the
picture name and all other information is returned from S3IPIC.
Alternatively:
Call S3NPIC to open a new picture. All the same information as
described above is needed here also.
Call S3OPIC to open an old picture supplying only the picture
name. All information about the old picture is returned here
also.
Call SIRPIC to open a picture in read-only state. You supply
the picture name, but no information about the picture is
returned.

C
PICNAM = DEFAULT GRAPHICS
IFOLD = NEW
IFABSC = 0
IFPRJ = 1
IBRTIP = 2
IABSSC = 0
LONMND = 0
LONMNM = 0
LONMNS = 0
LONMXD = 0
LONMXM = 0
LONMXS = 0
LATMND = 0
LATMNM = 0
LATMNS = 0
LATMXD = 0
LATMXM = 0
LATMXS = 0
IHEM = 0
IUTMCD = 0
IPJCOD = 0
ISPCOD = 0
IUNCOD = 0
IRADTY = 0
XOFFST = 1.0
FREEX = 1.0
YOFFST = 1.0
FREEY = 1.0
VXMIN = 0.0
VXMAX = 10.0
VYMIN = 0.0
VYMAX = 10.0
XSCMAP = 1.0
YSCMAP = 1.0
XLONG = 10.0
YLONG = 10.0
BOTPAR = 0.0
TOPPAR = 0.0
REFLAT = 0.0
SFLAT = 0.0
REFLON = 0.0
SFLON = 0.0
FNORTH = 0.0
FEAST = 0.0
UNTFAC = 0.0
AXISA = 0.0
AXISB = 0.0
AZMTH = 0.0
SCALE = 0.0
XLNVEW = 0.0
YLNVEW = 0.0

C
4 IPJCOD, ISPCOD, IUNCOD, IRADTY, VXMIN,
. YLNVEW, ISTAT )
5. Initialize an LGB.
Call SIGSOP to open a new LGB (graphics feature) on the
currently opened picture and currently opened ZGF. The only
input argument to this routine is the code assigned to the type of
graphic segment to be opened. You can find these codes in
Appendix A. Graphics Feature Codes in the Z-MAP Plus
Reference Manual.
C
C
LGBTYP = 1
6. Set attributes of the LGB.

For any type of LGB, the coordinate system can be defined. The
choices are engineering units (the units that data is measured in,
i.e., meters, feet, etc.,) or plotter units (inches or centimeters,
measured from the bottom left corner of the map). The default is
engineering units because rarely is data stored in plotter units.
All types of LGBs can be divided into four groups of graphic
primitives: lines, text, symbols and polygons. The following
routines are used depending on the type of graphics primitives to
be generated.
If the type of segment contains lines, the following attributes can
be assigned:
Attribute Routine
line color SIGLCL
line type SIGLTY (solid, bold, dashed)
dash and hachure size SIGLPM
line width SIGLWD

If the type of segment contains markers or symbols, the following

attributes can be assigned:
Attribute Routine
marker color SIGMCL
marker height SIGMHT
marker type SIGMTY
The marker type is the symbol code to use. You can find it in
Appendix C. Symbols, Fonts, and Line Patterns in the
If the type of segment contains text, the following attributes can be
assigned:
Attribute Routine
text color SIGTCL
text font SIGTFO
text height SIGTHT
text justification SIGTJU
text rotation SIGTRO
The text fonts are illustrated in Appendix C. Symbols, Fonts, and

Line Patterns in the Z-MAP Plus Reference Manual. Text
justification allows the location given for the text to be at the lower
left corner, lower right corner or the exact center of the text string.
If the type of segment contains polygons, only the fill color can be
set, using SIGPCL.
Alternatively, you could call SIGPDF to set all these attributes,
and the coordinate system.
C
C SET DEFAULTS
C
CALL SIGPDF(
7. Write graphics primitives.

After appropriate graphic attributes have been set, call routines to
write the actual graphic primitives to the picture. Call SIGLIN to
draw lines, call SIGMRK to draw symbols, call SIGTXT to draw
text, and call SIGPFL to draw polygons.

C
C
NUMPTS = 5
XCORS(1) = 1.0
YCORS(1) = 1.0
XCORS(2) = 11.0
YCORS(2) = 1.0
XCORS(3) = 11.0
YCORS(3) = 11.0
XCORS(4) = 1.0
YCORS(4) = 11.0
XCORS(5) = 1.0
YCORS(5) = 1.0
C
8. Close the LGB.

Call SIGSCL to close the currently open LGB after all graphics
have been added. After closing the current LGB, you can open
another one with another call to SIGSOP. See step 5 on page 229.
C
C
CALL SIGSCL(ISTAT)

After all graphics have been added to a picture, the picture must be
closed. Call SIEPIC to close the currently open picture. After
closing the current picture, you can open another new or old
picture and continue processing.
C
C CLOSE THE FIRST PICTURE
C
CALL SIEPIC (ISTAT)
Warning Close Picture before Closing ZIGS
It is important to close the picture before exiting the program to avoid

possible problems when you try to use the picture again.

10. Close the ZGF.

When you finish processing all pictures on the currently attached
ZGF, you must close it. Call SIEZGF to detach the current ZGF.
After detaching the current ZGF, you can open another ZGF if
necessary.
C
C CLOSE THE GRAPHICS FILE
800 CALL SIEZGF
Warning Close ZGF before Closing ZIGS
If the ZGF is not closed before exiting the program, you might have
problems when you try to use the ZGF again.

Unlike the ZIMS environment, the ZIGS environment needs to be
closed before exiting the program. Call SIEZIG to close ZIGS.
CALL SIEZIG

Call SIESIL to close the ZPI/O environment.

Output Graphics from a Picture

Occasionally, you must extract data from a picture in a ZGF in order to
add it to graphics data generated by another source. After the output
graphics environment is activated, the LGBs (graphics features) are
searched for those required for the project. If an LGB is found whose
graphics contents are wanted, that information is extracted from the
picture.
The general procedure for extracting graphics from a picture is:
3. Initialize a ZGF graphics file.
5. Initialize the output graphics environment.
6. Obtain a graphics feature (LGB) from the picture.
7. Retrieve the LGB.
8. Close the output graphics environment.
10. Close the ZGF.
To extract graphics from a picture, follow these steps:

1. Initialize ZPI/O, ZIGS, the ZGF, and the picture.
Call SICOMM or SIISIL, SIIZIG, SIIZGF, and S3IPIC, S3OPIC
or SIRPIC to set up the environment for extraction of graphics. For
more detail, see pages 226 to 227.
2. Open the output graphics environment.

Call SOGINT to activate the output graphics environment.
Arguments sent to this routine control how the output is returned
to the applications program. You can choose to have the system
return text, symbol and line LGBs as entities or as vectors.
3. Obtain an LGB.
Call SOGLGB to return the first LGB (graphics feature) header.
An output argument tells you what type of graphic segment has
been retrieved. If you do not want to add this type of graphics
feature to your application, call SOGLGB again to retrieve the
next LGB header.

4. Retrieve output graphics.

If the graphics segment retrieved by SOGLGB is of a type that you
want to add to your application, call S3GELM to retrieve the data.
Output arguments handle any of the four types of graphics
primitives that can be retrieved (lines, text, symbols or polygons).
Call S3GELM until a flag tells you the end of data for this LGB
has been reached, then call SOGLGB to get the next LGB header.
Stay in this SOGLGB/S3GELM loop until a flag from SOGLGB
tells you that all data for the picture has been reviewed.
5. Close the output graphics environment.

After all data has been reviewed, call SOGEND to close the output
graphics environment.
6. Close the picture, the ZGF and the ZIGS environment.

Call SIEPIC, SIEZGF and SIEZIG to close the picture, ZGF, and
ZIGS environment, as described on page 231.


Appendix B.
ZIMS Overview
Introduction
On many computing systems, file handling is not as user friendly as it

could be. Converting datasets (control points, grids, vertices, text, etc.)
located on separate disk files into member files on one large Z-MAP
Information Management System (ZIMS) master file minimizes this
type of problem. We have localized this interface to one level of
application programming. Many of the routines in the File Utilities
section of the Z-MAP Plus I/O Access Library are the interface used
for ZIMS. The ZIMS master file is commonly called an MFD.
The ZIMS master file has a system of expanded member file headers
which contain detailed information about the individual member files
history and parameters. This header provides easy access to ZIMS file
handling capabilities for all application programs, whether reading
from or writing to a permanent, temporary or scratch ZIMS member
file. This header also provides a standardized method for dealing with
control point datasets having different record structures. The record
structure information is stored in the member files header at the time
of creating and is available on subsequent reads of the member file.
As many as four master files can be attached to ZIMS simultaneously.
In addition, a scratch file is available which can be used for member
files that are only needed temporarily. The scratch master file is deleted
automatically at the end of the ZPI/O run; therefore, information about
the scratch master file cannot be accessed in future ZPI/O program
runs.
This appendix is an introduction to ZIMS for the new ZPI/O
programmer and a ZIMS reference for the more experienced ZPI/O
programmer. The next topic describes the ZIMS file structure followed
by a topic that describes step-by-step how to write and read a ZIMS
member file.
235 Appendix B. ZIMS Overview R2003.0

ZIMS File Structure
Master File
The basic ZIMS structure is the master file, a direct access binary file
with fixed record length. Each master file is a collection of independent
member files. The general structure of a master file is illustrated below.
MFD Header
Header File 1
Parameter Record (Grid)
Grid Column 1 Data
Grid Column 2 Data
Grid Column n Data
Header File 2
Parameter Record (Data)
Field Descriptor 1
Field Descriptor 2
Field Descriptor n
Data Record 1
Data Record n
ZIMS File Structure
R2003.0 Appendix B. ZIMS Overview 236

Member File
Each member file is conceptually separate from the other files and can
be used without regard to the other member files. Several types of files
have been defined, including grid files, data files, vertex files and fault
files. (For a list, see Appendix B. File and Field Codes in the
Z-MAP Plus Reference Manual. For examples of how these files are
structured, see Appendix D. Import/Export in the Z-MAP Plus
Reference Manual.)
In addition to the actual data, each member file can contain other
optional information. A history block contains information about other
files which were used in creating the fields, and can include text
descriptions input by the user. A parameter record contains descriptive
numerical information about the data in the file, and data field
descriptors contain information about the various fields in the data file.
There is no limit to the number of member files which can be in a
master file. Files can be added or deleted during a run. Each member
file in a given master file must have a unique name. If you try to create
a new member file in a master file which already has a member file by
that name, the ZPI/O routines place a version number (V-02, V-03,
etc.) in columns 21-24 of the member filename. The new member file
then has to be accessed by the name including version number. If the
version number is left off the name when accessing it later, the old or
original member file by that name is used.
Each member file has a 32-word directory associated with it, which is
sorted on the master file. At runtime, all directory entries from all the
master files are combined in one runtime directory. If a member file is
actually in use, a copy of the directory is placed in memory. The
directory contains the name and length of the file, and points to various
parts of the file and other information.
Gaining Access to a Member File

Accessing a member file is conceptually similar to accessing a master
file on a FORTRAN logical unit. Instead of using a unit number, a
ZIMS file is accessed through a file number, which is returned to the
user by the routine which opens the file. This number is called the
ZIMS logical file code and is used as an argument to the other routines
that access the file. The logical file code relates to a buffer where the
information about the file is stored. Since only a limited number of
buffers are available and can be open at one time (five is the usual
limit) the programmer must be sure to close the file when finished with
it.

Member File Structure

Member files are stored in two basic ways. Grids use the first method
while all other data types use the second method. For additional
information and examples, see Appendix D. Import/Export in the
Grid File Structure

The first record of a grid file is a header record. This record contains
information about the file such as file name, type (GRID), location of
next file header, etc. This record is followed by a parameter record
containing information such as minimum and maximum x, y, and z
values, number of rows and columns in the grid, ZNON (missing or
null data) value, and x and y grid intervals. Following the parameter
record is the data, which is stored column-wise, from top to bottom,
with the columns stored left to right.
Parameter Record for Grids

LENGTH = 32 words
Word Type Content AKA
1 Integer 0 (zero)
2 Integer Number of grid rows NROWS
3 Integer Number of grid columns NCOLS
4
56 Double Minimum x value XMIN
78 Double Maximum x value XMAX
910 Double Minimum y value YMIN
1112 Double Maximum y value YMAX
13 Real The x grid increment GXINC
14 Real The y grid increment GYINC
15 Real The x expansion of collection region over AOI XBAND
16 Real The y expansion of collection region over AOI YBAND
17 Real Reach, data collection radius REACH
18 Real Null data value for file ZNON
19 Real Maximum grid value GMAX
20 Real Minimum grid value GMIN
2132 Not used

Data File Structure

The second method of storing data is used by well data, seismic data,
fault data, lineal features, etc. The first record is similar to the first
record of a grid file., containing information about file name, type, etc.
The second record is a parameter record. For data files, the parameter
record contains the minimum and maximum x and y values, the number
of fields on the file, the length of each record, the number of records,
the ZNON value, a sort flag, etc.
Parameter Record for Data

LENGTH = 32 words
Word Type Content AKA
1 Integer Number of fields on data record (also the number NFLDS
of field descriptor records)
2 Integer Number of words per data record (equal to the sum NWRDS
of the number of words entries from all the field
descriptors)
3 Integer Number of data records in file NRECS
4 Integer Distribution type code (See the list below.)
56 Double Minimum x coordinate XMIN
78 Double Maximum x coordinate XMAX
910 Double Minimum y coordinate YMIN
1112 Double Maximum y coordinate YMAX
1317
18 Real Null data value for file ZNON
1920
21 Real Marker or separator value for contour, seismic
section, or cross-section files
22
23 Integer CNTR file mode. 1 = equal interval, 2 = unequal
interval, 3 = unknown
24 Real Contour interval for contour file if CNTR file
mode (word 23) = 1
2529
30 Real Rotation angle
31 Integer Process flag. 1 = batch setup, 2 = interactive,
3 = batch
32 Integer Primary sort field
Distribution Type Code:
1 = Irregularly spaced in x,y
2 = Sequentially spaced
3 = Irregular but ordered in increasing x with increasing y for equal x

Data files also contain Field Descriptor records. One field descriptor
record is needed for each field on the dataset. Each record contains the
field name, field type, default print information, location in the record,
the ZNON value, and minimum and maximum allowed values.
Field Descriptor Record

LENGTH = 20 words
Word Type Content
15 Hollerith 20-character name for the field. Defaults to sequence number
if blank.
6 Integer Type of data stored in the field. The standard data types are
given in Appendix B. File and Field Codes in the
7 Hollerith Default print/transfer format code (A, G, F, E, (I))
8 Integer For Real fields, field width for print format.
For Char fields, maximum number of characters.
9 Integer For Real fields, number of decimal places for print format.
10 Integer Index position of first word for field in each record. This
indicates the location (word number) in the record where the
data for this field begins.
11 Integer Number of consecutive words in the data record that are
assigned to this field. More than one word is needed for
double precision fields, and may be needed for character type
fields.
12
13 Real Field null data value (ZNON) (default = 1.0E30).
14 Real Field minimum allowed value (default = 1.0E30).
15 Real Field maximum allowed value (default = +1.0E30).
1619
20 Integer Points to next secondary sort field (zero if none).
The data files can also be described as a two-dimensional matrix where

the field descriptors are the columns of the matrix and the data records
are the rows. Using this analogy, a file could look like the following:
X-field Y-field Z1-field Name-field

record 1
record 2
record 3

record (maximum)
The data records follow the final field descriptor record.

ZIMS Programmers Guide
This topic is a tutorial on the use of ZIMS in ZPI/O application

programs. The first example describes creating a member file. The
second example describes reading data from an existing member file.
The topic also includes a description of reading and writing grid files.
Creating a Member File

The general procedure for creating a member file is:
2. Create a master file.
3. Initialize the ZIMS environment.
4. Create a new data file.
5. Create parameter and field descriptor records.
6. Write data records to the member file.
7. Close the member file.
8. Close the ZIMS environment.
The steps for creating a member file are:

units, etc., used in the entire ZPI/O system.
serious and many types of errors when you call other ZPI/O routines.
2. Create a ZIMS master file.

Call SIMFCR to create a master file. Arguments include the disk
name of the master file and an internal name for identification in
printouts. These names can be identical if you want.


Call SIIZIM to initialize the ZIMS environment and attach all
master files used in this run. Input arguments include the number
of master files to attach and their names. The master files must
already exist.
4. Create a new member file.

Call SINOPN to create a new member file. Input arguments are the
name for the member file, the master file number where it is
stored, and a four-character code for the type of file to be created.
(For information about these codes, see Appendix B. File and
Field Codes in the Z-MAP Plus Reference Manual.) Output
arguments are the name of the file (with added version number if
necessary), the ZIMS logical file code, and a status flag.
5. Create field descriptor records.

Each record consists of fields in which the data is stored. The
contents of each field are defined by a field descriptor record. For
information about the format of the field descriptor record, see the
Field Descriptor Record table on page 240.
Call SIFLDW to write the field descriptor records. The logical file
code is returned when the file is opened.
Write Order
The field descriptor records must be written to a new file before the data
records are written to ensure correct file usage.
6. Write data records to the file.

Call SIFWRT to write in sequential order the data records for a
new member file on the master file. Input arguments include the
logical file code of the member file, the record number (it should
always be 0 when writing to the file sequentially), the number of
words of data to write, and the data itself.

7. Create the parameter record.

The parameter record completes the definition of the file. The
parameter record is written after all data records have been written
in order to have correct values for minimum and maximum x and y
values and a correct record count. For information about the
format of the parameter record, see Parameter Record for Data
table on page 239.
Call SIPRWD to write the parameter record for all data types
except grids. Call SIPRWG to write the parameter record for grids.
In both cases, one of the arguments is the logical file code returned
when the file is opened.

Call SIFCLO to close the member file and release the buffer
relating to the logical file code. Closing a new member file writes
the files header information to the disk so it can be accessed later.


Reading Data from an Existing ZIMS File

To retrieve data from a currently existing member file in a master file,
you must take several steps. You must open an old ZIMS member file,
read and interpret the parameter record and field descriptor records, and
finally read the data.
The steps for reading data from a ZIMS member file are:
1. Initialize ZPI/O environment.
units, etc., used in the entire ZPI/O system.
serious and many types of errors when you call other ZPI/O routines.

Call SIIZIM to initialize the ZIMS environment and attach all
master files used in this run. Input arguments include the number
of master files to attach and their names. The master files must
already exist.
3. Open an existing ZIMS member file.

Call SIOOPN to open an old member file. Input arguments for this
routine include the name of the member file (with version number
if needed) and the name of the master file which contains the
member file. (Different master files attached to the same run could
possibly contain member files with the same name and without
version numbers.) SIOOPN returns the type of file opened and the
logical file code to be used in subsequent processing.
4. Read and interpret the parameter record.

To read and decode a ZIMS data file, it is necessary first to read
the parameter record. Call SIPRRD to read the parameter record
for a data file (call SIPRRG to read the parameter record for a grid
file). The input argument is the logical file code. All other features
of the parameter record are returned as output arguments from the
routine.

5. Read and interpret the field descriptors.

One of the arguments returned by SIPRRD is the number of fields
contained in the member file. A loop must be set up to read the
field descriptor records for all the fields on the file. Call SIFLDR
to read each field descriptor in turn. Input arguments are the
logical file code and the field number to be retrieved. Output
arguments are the field name, field type, ZNON value, print codes,
etc.
6. Read the data records.

The parameter record you read in step 4 indicates the length of
each record to read and the number of records on the file. Reading
an entire data file is simply a matter of calling SIFRED once for
each record on the file. The field descriptors provide pointers to
data fields in each record, along with other field-specific
information. After reading each record, the data of interest can be
extracted according to the field location descriptions.

Call SIFCLO to close the member file and release the buffer
relating to the logical file code.


Reading and Writing Grids

The grid type of member file is ideal for storing data which is
organized as a two-dimensional matrix. The parameter record for grids
(as described in Parameter Record for Grids table on page 238)
specifies the dimensions of the matrix as the number of rows and
columns in the grid. Other parameters describe the range of the x and y
coordinates that the grid covers and the ZNON (no data) value. Call
SIPRRG to read the parameter record for a grid file. Grid files require
no field descriptor records.
Data is stored on the file in column order from the top down. The first
column is the far left (minimum x) column of the grid and the last is the
far right (maximum x) column of the grid. In each column, the first
value is the top (maximum y) value in the column and the last value is
the bottom (minimum y) value of the column.
Grids are read and written with the same routines used for reading and
writing records of data SIFRED for reading and SIFWRT for
writing. The number of words to read or write is the number of rows in
the grid and the number of records to read or write is the number of
columns in the grid.
For additional information, see Reading and Writing Grids on
page 34.

C
Appendix C.
Logical Unit Assignment
The Logical Unit Assignment Table contains a list of the logical

FORTRAN units used throughout ZPI/O.
R2003.0 Appendix C. Logical Unit Assignment 247

R2003.0
Landmark Graphics
Logical Unit Assignment Table
Description Logical Symbolic Common Defining Data Maximum Record Record File
Unit Name Block Routine Format Size Format Length Allocation
Volumetrics output 9 LFRMAT (none) ZVOLUM Character 200 rec. Fixed 132 byte Permanent
Blocked (if used)
Import Task formatted data input/outputmay be 10 LUNFMT (none) ZXFGRD Character User Permanent
unused. ZXFDAT Specified (if used)
ZXFSUP
ZIMS Runtime File Directory (RTD), contains a list 20 LUNDIR DIRECT ZILDDR Binary 250 rec. Direct 32 word Run
of all datasets accessed in this run. Temporary
ZIMS Master Files (MFD), contain all data listed in 21 (none) FBUFCM ZILDDR Binary 500 rec. Direct 512 word Permanent
RTD above. 22 FBUFCM Access
23 FBUFCM
24 FBUFCM
ZIMS Scratch MFD used for run-temporary 25 (none) FBUFCM ZILDDR Binary 500 rec. Direct 512 word Run
datasets. Access Temporary
ZIMS Scratch file used for MFD file deletion and 26 LUNNEW (none) ZIGRCL Binary 500 rec. Direct 512 word Run
clean up. 26 LUNSCR (none) ZIMFDD Access Temporary
Appendix C. Logical Unit Assignment
ZIGS Graphics File (ZGF), contains new or old 27 LZGF ZGFCOM ZGFINF Binary 500 rec. Direct 128 word Permanent
plots. 27 LUNQ (none) ZMDSPL Access or Run
Temporary
ZIGS auxiliary Graphics File used for copy and 28 LUNAUX (none) ZGCOPY Binary 500 rec. Direct 128 word Permanent
cleanup. Access (if used)
ZIGS color table 39 LUNIT (none) ZDINIT Character 500 rec. Fixed/ 80 byte Permanent

Blocked
ZIGS Workstation file 40 LUN (none) ZGBGWD Character 400 rec. Fixed/ 80 byte Permanent
Blocked
Alternate color table (reading) 41 LUNIT (none) ZDCRCT Character 500 rec. Fixed/ 80 byte Permanent
Blocked (if used)
Alternate color table (writing) 42 LUNIT (none) ZDCWCT Character 500 rec. Fixed/ 80 byte Permanent
Blocked (if used)
Filter scratch file 76 LUNSCR (none) ZFBIHR Binary 800 rec. Direct 4096 word Run
76 LUNSCR SOBIHR Access Temporary
248
Logical Unit Assignment Table
249

Description Logical Symbolic Common Defining Data Maximum Record Record File
Unit Name Block Routine Format Size Format Length Allocation
Lithology symbol table 37 LUNSYM SCLOGU STISYM Binary 512 rec. Direct 512 byte Permanent
Appendix C. Logical Unit Assignment
Access
Log Curve Default File 51 LDFLG (none) SLOPEN Character Fixed/ 80 byte Permanent
LUNLOG SCLOGU SGCOMN Blocked
Lithology and Cross-Section Default File 52 LDEFS (none) SLOPEN Character Fixed/ 80 byte Permanent
LUNDEF SCLOGU SGCOMN Blocked
Definition File 53 LNLST (none) SLOPEN Character Fixed/ 80 byte Permanent
LGNLST SCLDMX SLCOMM .Blocked
Lithology Data File 55 LLITH (none) SLOPEN Character Fixed/ 80 byte Permanent
LUNLIT SCLDMX SLCOMM Blocked
Tops Data File 56 LTOPS (none) SLOPEN Character Fixed/ 80 byte Permanent
LUNTOP SCLDMX .SLCOMM .Blocked
Log Curve Data File 57 LLOGS (none) SLOPEN Character Fixed/ 80 byte Permanent
LUNLOG SCLDMX SLCOMM Blocked
Analysis Data File 58 LANLY (none) SLOPEN Character Fixed/ 80 byte Permanent
LUNANL SCLDMX SLCOMM Blocked
Core Data File 59 LUNCOR SCLDMX SLCOMM Character Fixed/ 80 byte Permanent
Blocked
Well Survey Data File 60 LWSV (none) SLOPEN Character Fixed/ 80 byte Permanent
LUNWSR SCLDMX SLCOMM Blocked
Landmark Graphics
R2003.0
R2003.0 Appendix C. Logical Unit Assignment 250

Index
Symbols D
.assemble picture debugging option
copy to space vs. copy from space 151 using 29
defaults
set field descriptors 184186
A set for lines, markers, text, and polygons 129131
A-MAP Plus I/O define coordinate system 134
example program 1424 delete
argument name graphics feature from picture file 135
variable vs. constant 29 mark picture for 159
assemble picture 149152 member file from master file 170
copy to space vs. copy from space 157 detach one or all master files 202
compute four corners for 155158 display area of a picture 100, 108, 144
attach master file 177, 198 display/plot hardcopy type picture 7273
draw
connected line segments 121
C lines using a member file 74
lines using array inputs 70
close
markers 78
current graphics feature 133
shaded or colorfilled polygon 132
files 30
text 142
graphics file 118
last picture opened 117
master files 188 E
member file 189
ZIMS files 40 example program
color table 224 to list members of a graphics file 1013
compress to list members of a master file 89
graphics file 163
master file 199 G
compute
control point file statistics 5658 graphics feature
four corners of one picture relative to another picture defined 223
for assembly/overlay 155158 graphic primitives 224
grid file statistics 4648 set attributes 229230
statistics for field 5960 graphics file
convert from x,y to latitude/longitude 4953 close 133
copy all or part of a picture to another picture 153154 compress 163
create new master file 200 header 224
create new member file 32, 241243 open 145
transfer picture from neutral file to 79
transfer picture to neutral file from 80164
graphics files
list members of, example program 1013
R2003.3.0.0 Index 251

grids list member files

reading and writing 34 example graphics program 1013
logical file code 237
logical unit assignment 247249
H
header 224 M
mark picture for deletion 159
I marker
IDBUG draw 78
using 29 set color 125
index maps 147148 set defaults 129131
initialize 38 set height 126
all input arguments 29 set type 127
ZPI/O environment 38 master file
with output file control 4142 attach 177, 198
ZPI/O output graphics environment 167 compress 199
Zycor Information Management System (ZIMS) and create new 200
attach master files 173174, 197 rename internal name of 204
Zycor Interactive Graphics Environment (ZIGS) 146 master files
internal routines close 188
draw/plot features 69 detach one or all 202
file utilities 169 list attached 203
graphic utilities 77 list members of, example program 89
initialize/terminate ZPI/O environment 36 specifying the number of 31
transfer, convert, list information 43 member file
internal routines, defined 29 create 32
ISTAT create new 241243
using 30 open new 205
open old 206
output filename 33
L position for sequential read 215
position for sequential write 220
LGB
read from 32
header 224
read from at random location 216
set attributes 229230
read from sequentially 31, 217
LGB, defined 223
read history information from 218
line
write history records to 219
draw connected segments 121
write to at random location 221
draw using a member file 74
write to sequentially 31, 222
draw using array inputs 70
set color 120
set dash and hachure mark parameters 122 O
set defaults 129131
set type 123 obtain
set width 124 color representation for color index 165
list general, projection and graphics feature information
attached master files 203 for picture 109115
data file 6668 graphics from a picture 233234
file history and its ancestry 175176 next graphics feature for picture 168
grid as grid or contours 6365 next valid graphics element from picture 8184
member files 171172 parameter, projection, and field information about data
example program 89 file 178183
picture name by picture index 160
R2003.3.0.0 Index 252

open R
files 30
graphics file 145 read
new graphics feature 136 data parameter record 209
new member file 32, 205 field descriptor 190191
new or old picture 85144 from member file 32, 244245
new picture 92100 from member file at random location 216
old member file 206 from member file sequentially 31, 217
old picture 101108 general data or contour parameter record 207208
old picture read only 162 grid 34, 246
overlay maps or generate index maps 147148 grid parameter record 210
overlay picture 149152 history information from member file 218
copy to space vs. copy from space 151, 157 position member file for sequential 215
compute four corners for 155158 record from member file 194
rename
internal name of master file 204
P picture 161
reset debug print flag 37
picture
retrieve information
copy to space vs. copy from space 151, 157
about member file from run time directory 187
copy all or part to another picture 153154
header 224
mark for deletion 159 S
obtain graphics element from 8184
obtain graphics from 233234 set
obtain information 109115 dash line and hachure mark parameters 122
obtain name by picture index 160 default field descriptors 184186
obtain next graphics feature for 168 defaults for lines, markers, text, and polygons 129
open new 92100 131
open new or old 85144 line color 120
open old 101108 line type 123
open old, read only 162 line width 124
place graphics 226232 marker color 125
projection arguments vs. projection type 107 marker height 126
rename 161 marker type 127
transfer from graphics file to neutral file 80164 polygon fill color 128
transfer from neutral file to graphics file 79 text color 137
polygon text font 138
draw shaded or colorfilled 132 text height 139
set defaults 129131 text justification 140
position member file text rotation 141
for sequential read 215 status flag, using 30
for sequential write 220 subroutine descriptions, presentation of information 25
28
253 Index R2003.3.0.0

T Z
terminate Z-MAP Interactive Graphics System
ZPI/O environment 39 file structure 223225
ZPI/O output graphics environment 166 file structure example 225
Zycor Interactive Graphics Environment (ZIGS) 119 programmers guide 226234
text Z-MAP Plus I/O
draw 142 program structure 6
set color 137 ZPI/O environment 38
set defaults 129131 Zycor Information Management System
set font 138 field descriptor record 240
set height 139 file structure 236240
set justification 140 file structure example 236
set rotation 141 parameter record for data 239
transfer parameter record for grids 238
contents (pictures) of neutral file to graphics file 79 programmers guide 241246
information from external file into member of master Zycor Information Management System (ZIMS)
file 4445 initialize and attach master files 173174, 197
information from member of master file to external file Zycor Interactive Graphics Environment (ZIGS)
6162 initialize 146
pictures from graphics file to neutral file 80164
V
variable argument name 29
W
write
data parameter record 213
field descriptor 192193
from member file sequentially 31
general data or contour parameter record 211212
grid 34, 246
grid parameter record 214
history records to member file 219
position member file for sequential 220
record to member file 195196
to member file at random location 221
to member file sequentially 222
R2003.3.0.0 Index 254

ZPIO

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

ZPIO

Încărcat de

Drepturi de autor:

Formate disponibile

Z-MAP Plus I/O Access Library

copyright 2002 by Landmark Graphics Corporation

625244 R2003.0 May 2002

Landmark Graphics Corporation

ZPI/O Overview ..............................................................................................................5

Initialize/Terminate ZPI/O Environment ..........................................................35

Transfer, Convert, or List Information .............................................................43

Draw and Plot Features ...........................................................................................69

Graphics Utilities ........................................................................................................77

SIIZIG Initialize the Z-MAP Interactive Graphics Environment (ZIGS) ............146

File Utilities ..................................................................................................................169

SIMFAT Attach a master file ..................................................................................198

Appendix A. ZIGS Overview ...............................................................................223

R2003.0 Contents vii

Appendix B. ZIMS Overview ...............................................................................235

Appendix C. Logical Unit Assignment .........................................................247

viii Contents R2003.0

The Z-MAP Plus I/O Access Library (referred to as ZPI/O) is a set of

Purpose of This Guide

The guide is intended to be read by experienced programmers who are

1 Introduction: Purpose of This Guide R2003.0

What Is in This Guide

This programmers guide provides information about each of the

Introduction (page 1) explains the purpose of this guide, who

ZPI/O Overview (page 5) explains what the Z-MAP Plus I/O

Initialize/Terminate ZPI/O Environment (page 35) lists the

Transfer, Convert, or List Information (page 43) lists the

Graphics Utilities (page 77) lists the subroutines used for

Appendix A. ZIGS Overview (page 223) explains the file

R2003.0 Introduction: What Is in This Guide 2

Appendix B. ZIMS Overview (page 235) explains the file

Appendix C. Logical Unit Assignment (page 247) lists the

The Index (page 252) references the function of the subroutines,

To make the information in this guide as accessible as possible, the

Examples of text you type in or text displayed on the screen are in

****** SIISIL - ERROR, PROBLEM OPENING FILES

A portion of an example of text you type in that is to be replaced

Some acronyms and abbreviations are used throughout this guide:

ZPI/O Z-MAP Plus I/O Access Library

3 Introduction: Typographic Conventions R2003.0

The following guides are available from your system administrator or

Z-MAP Plus Installation and Configuration

Each of these guides contains appendixes with information you may

ZCL Operators Manual presents the Zycor Command Language

Z-MAP Plus Reference Guide provides easy access to reference

R2003.0 Introduction: Related Documentation 4

The Z-MAP Plus I/O Access Library (referred to as ZPI/O) is a set of

This section contains information about the following topics:

Structure of Programs Using ZPI/O (page 6) outlines the

Subroutine Descriptions (page 25) describes the presentation of

Comments and Suggestions (page 29) includes general

5 ZPI/O Overview: Introduction R2003.0

Structure of Programs Using ZPI/O

General Structure of Programs Using ZPI/O

R2003.0 ZPI/O Overview: Structure of Programs Using ZPI/O 6

Sequence of Calls to Read or Write a ZIMS File

SINOPN to create and open the file

after all data is written:

SIFLDW for each field of a data file

SIOOPN to open existing file

R2003.0 ZPI/O Overview: Sequence of Calls to Read or Write a ZIMS File 7

Example Program for Listing Members of a Master File

This example is written on a Unix system and assumes that variables

Example Program for Creating Graphics