Z-MAP Plus I/O Access Library - Landmark Software Manager ...

Z-MAP Plus I/O Access Library 

copyright © 2008 by Landmark Graphics Corporation 

Release 5000.0.0 July 2008

© 2008 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 

2107 CityWest Blvd, Building 2, Houston, Texas 77042-3051, USA 

P.O. Box 42806, Houston, Texas 77242, USA 

Phone:713-839-2000 

FAX: 713-839-2015 

Internet: www.halliburton.com/landmark 

Trademarks 

3D Drill View, 3D Drill View KM, 3DFS, 3D Surveillance, 3DView, Active Field Surveillance, Active Reservoir Surveillance, ADC, Advanced 

Data Transfer, ARIES, ARIES DecisionSuite, AssetConnect, Asset Decision Solutions, Asset Development Center, AssetDirector, Asset Journal, 

AssetLink, AssetLink Advisor, AssetLink Director, AssetLink Observer, AssetObserver, AssetObserver Advisor, Asset Performance, 

AssetPlanner, AssetSolver, AssetSolver Online, AssetView, BLITZPAK, CasingLife, CasingSeat, COMPASS, Corporate Data Archiver, 

Corporate Data Store, Data Analyzer, DataManager, DataStar, DBPlot, Decision Management System, DecisionSpace, DecisionsSpace 3D Drill 

View KM, DecisionSpace AssetLink, DecisionSpace AssetPlanner, DecisionSpace AssetSolver, DecisionSpace AssetView 2D, DecisionSpace 

AssetView 3D, DecisionSpace Atomic Meshing, DecisionSpace Decision Management Systems(DMS), DecisionSpace for Production, 

DecisionSpace Infrastructure, DecisionSpace Nexus, DecisionSpace PowerModel, DecisionSpace PrecisionTarget, DecisionSpace Reservoir, 

DecisionSpace TracPlanner, DecisionSpace Well Seismic Fusion, DecisionSpace WellSolver, DecisionSuite, DepthTeam, Depth Team, 

DepthTeam Explorer, Depth Team Explorer, DepthTeam Express, Depth Team Express, DepthTeam Extreme, Depth Team Extreme, DepthTeam 

Interpreter, Depth Team Interpreter, Desktop Navigator, DESKTOP-PVT, DESKTOP-VIP, DEX, DIMS, Discovery, Discovery Asset, Discovery 

FrameBuilder, DMS, Drillability Suite, Drilling Desktop, DrillModel, Drill-to-the-Earth Model, DSS, Dynamic Reservoir Management, Dynamic 

Surveillance System, EarthCube, EDM, EDT, eLandmark, Engineer’s Data Model, Engineer's Desktop, Engineer’s Link, ESP, Event Similarity 

Prediction, ezFault, ezModel, ezSurface, ezTracker, FastTrack, FG+, FieldPlan, Field Scenario Planner, FZAP!, GeoAtlas, GeoDataLoad, 

GeoGraphix, GeoGraphix Exploration System, GeoLink, GeoProbe GF DataServer, GES, GES97, GESXplorer, GMAplus, GMI Imager, 

GRIDGENR, Handheld Field Operator, HHFO, I2 Enterprise, iDIMS, IsoMap, iWellFile, i Wellfile, KnowledgeSource, Landmark, Landmark 

Decision Center, Landmark & Design, Landmark Logo and Design, Landscape, Lattix, LeaseMap, LMK Resources, LogEdit, LogM, LogPrep, 

Make Great Decisions, MathPack, MIMIC, MIMIC+, Model Builder, MyLandmark, Nexus, Object MP, OpenBooks, OpenJournal, OpenSGM, 

OpenVision, OpenWells, OpenWire, OpenWorks, OpenWorks Development Kit, OpenWorks Well File, OpenWorks Production, PAL, Parallel- 

VIP, PetroBank, PetroBank Explorer, PetroBank Master Data Store, PetroWorks, PetroWorks Asset, PetroWorks Pro, PetroWorks ULTRA, 

PlotView, Point Gridding Plus, Pointing Dispatcher, PostStack, PostStack ESP, PostStack Family, PowerCalculator, PowerExplorer, 

PowerExplorer Connect, PowerGrid, PowerHub, Power Interpretation, PowerJournal, PowerModel, PowerView, PrecisionTarget, Presgraf, 

PRIZM, Production Asset Manager, Production, PROFILE, Project Administrator, ProMAGIC, ProMAGIC Connect, ProMAGIC Server, 

ProMAX, ProMAX 2D, ProMAX 3D, ProMAX 3DPSDM, ProMAX 4D, ProMAX Family, ProMAX MVA, ProMAX VSP, pSTAx, Query 

Builder, Quick, Quick+, QUICKDIF, QuickWell, QuickWell+, QUIKRAY, QUIKSHOT, QUIKVSP, RAVE, RAYMAP, RAYMAP+, Real 

Freedom, Real Time Asset Management Center, Real Time Decision Center, Real Time Operations Center, Real Time Production Surveillance, 

Real Time Surveillance, Real-Time View, Reference Data Manager, Reservoir Framework Builder, RESev, ResMap, RightTime, RTOC, SCAN, 

SeisCube, SeisMap, SeisModel, SeisSpace, SeisVision, SeisWell, SeisWorks, SeisWorks 2D, SeisWorks 3D, SeisWorks PowerCalculator, 

SeisWorks PowerJournal, SeisWorks PowerSection, SeisWorks PowerView, SeisXchange, Semblance Computation and Analysis, Sierra Family, 

SigmaView, SimConnect, SimConvert, SimDataStudio, SimResults, SimResults+, SimResults+3D, SIVA+, SLAM, smartSECTION, Spatializer, 

SpecDecomp, StrataAmp, StrataMap, StrataModel, StrataSim, StrataWorks, StratWorks, StratWorks 3D, StreamCalc, StressCheck, STRUCT, 

Structure Cube, Surf & Connect, SynTool, SystemStart, SystemStart for Clients, SystemStart for Servers, System Start for Servers, SystemStart for 

Storage, Tanks & Tubes, TDQ, Team Workspace, TERAS, The Engineer’s Desktop, Total Drilling Performance, TOW/cs, TOW/cs Revenue 

Interface, TracPlanner, TracPlanner Xpress, Trend Form Gridding, Turbo Synthetics, VESPA, VESPA+, VIP, VIP-COMP, VIP-CORE, 

VIPDataStudio, VIP-DUAL, VIP-ENCORE, VIP-EXECUTIVE, VIP-Local Grid Refinement, VIP-THERM, WavX, Web Editor, Wellbase, 

Wellbore Planner, Wellbore Planner Connect, WELLCAT, Well Cost, WELLPLAN, Well Seismic Fusion, WellSolver, WellXchange, WOW, 

Xsection, You're in Control. Experience the difference, ZAP!, and Z-MAP Plus are trademarks, registered trademarks or service marks of 

Landmark Graphics Corporation. 

All other trademarks, service marks and product or service names are the trademarks or names of their respective owners.

Landmark acknowledges that certain third party code has been bundled with, or embedded in, Landmark’s software. 

The licensors of this third party code, and the terms and conditions of their respective licenses, may be found at the 

following location: 

[Installdir]\docs\Third_Party.pdf

International Trade Compliance 

This application is manufactured or designed using U.S. origin technology and is therefore subject 

to the export control laws of the United States. Any use or further disposition of such items is 

subject to U.S. law. Exports from the United States and any re-export thereafter may require a 

formal export license authorization from the government. If there are doubts about the 

requirements of the applicable law, it is recommended that the buyer obtain qualified legal advice. 

These items cannot be used in the design, production, use, or storage of chemical, biological, or 

nuclear weapons, or missiles of any kind. 

The ECCN’s provided in Release Notes represent Landmark Graphics' opinion of the correct 

classification for the product today (based on the original software and/or original hardware). 

Classifications are subject to change. If you have any questions or need assistance please contact 

us at FHOUEXP@halliburton.com 

Under the U.S. Export Administration Regulations (EAR), the U.S. Government assigns your 

organization or client, as exporter/importer of record, responsibility for determining the correct 

authorization for the item at the time of export/import. Restrictions may apply to shipments based 

on the products, the customer, or the country of destination, and an export license may be required 

by the Department of Commerce prior to shipment. The U.S. Bureau of Industry and Security 

provides a website to assist you with determining the need for a license and with information 

regarding where to obtain help. 

The URL is: http://www.bis.doc.gov 

Definitions 

CCATS (Commodity Classification Automated Tracking System) - the tracking number assigned 

by the U.S. Bureau of Industry and Security (BIS) to products formally reviewed and classified by 

the government. The CCATS provides information concerning export/re-export authorizations, 

available exceptions, and conditions. 

ECCN (Export Control Classification Number) -The ECCN is an alpha-numeric code, e.g., 3A001, 

that describes a particular item or type of item, and shows the controls placed on that item. The 

CCL (Commerce Control List) is divided into ten broad categories, and each category is further 

subdivided into five product groups. The CCL is available on the EAR Website.

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 

5000.0.0 6


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 file ....................44 

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 

5000.0.0 Contents 7

Z-MAP Plus I/O Access Library Landmark Graphics 

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 

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 

8 Contents 5000.0.0


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 

5000.0.0 Contents 9


SIGTRO 

Set text rotation.............................................................................................................141 

SIGTXT 

Draw text.......................................................................................................................142 

SIIZGF 

Open a graphics file ......................................................................................................145 

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/overlay155 

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 

10 Contents 5000.0.0


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 files173 

S2LHIS 

List the history and ancestry of a member file..............................................................175 

S2MFAT 

Attach a master file indicating either read-only or read-write file access ....................177 

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 files197 

SIMFAT 

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

SIMFCM 

Compress a master file..................................................................................................199 

5000.0.0 Contents 11


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 

12 Contents 5000.0.0


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 Programmer’s Guide...........................................................................................226 

Input Graphics to a Picture ....................................................................................226 

Output Graphics from a Picture .............................................................................233 

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

ZIMS File Structure ......................................................................................................236 

Master File .............................................................................................................236 

Member File ...........................................................................................................237 

ZIMS Programmer’s Guide ..........................................................................................242 

Creating a Member File .........................................................................................242 

Reading Data from an Existing ZIMS File ............................................................245 

Reading and Writing Grids ....................................................................................247 

Appendix C. Logical Unit Assignment .........................................................248 

Index ................................................................................................................................252 

5000.0.0 Contents 13


Overview 

Purpose of This Guide 

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. 

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. 

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 5000.0.0


What Is in This Guide 

This programmer’s 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. 

5000.0.0 Introduction: What Is in This Guide 2


Typographic Conventions 

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 248) 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. 

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 5000.0.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 Operator’s 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 Operator’s 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. 

5000.0.0 Introduction: Related Documentation 4


Introduction 

ZPI/O 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. 

The routines included in the ZPI/O Access Library are compiled under 

FORTRAN 77. Every reasonable effort has been made to minimize 

system dependencies—if 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 5000.0.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 

5000.0.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 

5000.0.0 ZPI/O Overview: Contents 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: Contents 5000.0.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 



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 



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 



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 



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 



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’ 



C 


IF (ISTAT .GT. 0) GO TO 800 



C 

PICNAM = ’DEFAULT GRAPHICS ’ 


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 



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, IRDATY VXMIN, 








C 


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 



C 

C OPEN POLYGON LINES PICTURE SEGMENT 

C 

LGBTYP = 7 



C 

C DO A MARKERS AND LINES USING LINES 



C 

C 

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 

CALL SIGMRK(NUMMRK, XCORS, YCORS, ISTAT ) 


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 



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 



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 



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 



C 

C CLOSE THE FIRST PICTURE 

C 


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 ’ 


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 



XLONG = 10.0 

YLONG = 10.0 

BOTPAR = 0.0 

TOPPAR = 0.0 

REFLAT = 0.0 

SFLAT = 0.0 



C 

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 





4 IPJCOD, ISPCOD, IUNCOD, IRADTY VXMIN, 








C 


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 



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 



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 





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 



C 

C CLOSE THE SECOND PICTURE 

C 



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 

Major ZPI/O Groupings 

Presentation of Information 

The most important parts of this guide are the subroutine descriptions. 

Considerable effort has gone into constructing a set of consistent 

interfaces. 

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) 

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 5000.0.0


Name 

Function 

Note 

Environment 

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. 

This is a brief, one-line description of what the subroutine does. 

Additional detail is provided in the paragraph(s) that follow. 

Included are notes about arguments and other subroutines, examples, 

hints and suggestions. 

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. 

5000.0.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 are arranged in a table of three columns: 

Argument Name 

argument name 

data type 

description and default 

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 5000.0.0


Data Type 

Description 


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. 

The description column contains a brief explanation of the argument’s 

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 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). 

5000.0.0 ZPI/O Overview: Subroutine Descriptions 28


Comments and Suggestions 

Internal Routines 

Initializing Input Arguments 

Calling Arguments 

Using the Debug Option, IDBUG 

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. 

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. 

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. 

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 5000.0.0


Using the Status Flag Option, ISTAT 

Opening and Closing Files 

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. 

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 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. 

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 

5000.0.0 ZPI/O Overview: Comments and Suggestions 30


Master File Numbers 

Reading Sequential Data 

Writing Sequential Data 

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 

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. 

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 

Creating 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. 

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 242. 

5000.0.0 ZPI/O Overview: Comments and Suggestions 32


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. 

YMAX 

1 

2 

3 

4 

5 

6 

7 

8 

9 

Columns 

1 2 3 4 5 6 7 8 9 101112 

10 

11 

XX 

12 

YMIN YMIN 

Rows 

XMIN 

XMIN 

For additional information, see ”Reading and Writing Grids” on 

page 247. 

5000.0.0 ZPI/O Overview: Comments and Suggestions 34 

XMAX 

XMAX YMAX


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. 

5000.0.0 Initialize/Terminate ZPI/O Environment: Introduction 35



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 – 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

IDBUG I Whether to print debug statements: 

0 = Off, do not print debug statements 

1 = On, print the debug statements 

Data 

Type 

Description 

and Default 

ISTAT I Status flag: 

0 = Operation was successful 

1 = Error, debug print file cannot be opened. 

IDBUG reset to zero 

5000.0.0 Initialize/Terminate ZPI/O Environment: Internal Routines – S2DBUG 37



SICOMM 

Function Initialize the ZPI/O environment 

This subroutine initializes system-wide common blocks. SICOMM or SIISIL 

(page 41 – a replacement subroutine for SICOMM) must be the first 

subroutine called when using the Z-MAP Plus I/O Access Library. 

SICOMM 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 ) 


Argument 

Name 

Output Arguments None 

Data 

Type 

Description 

and Default 



1 = On, print debug statements 

LTHWRK I Length of the workspace. It must be at least 3. 

See ”Environment” above. 

38 Initialize/Terminate ZPI/O Environment: Internal Routines – SICOMM 5000.0.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 


Argument 

Name 

Data 

Type 

Description 

and Default 



1 = Error, problem closing the files 

5000.0.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 5000.0.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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 



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: 0–99 

LUNSTA I Logical unit number for output statistical (report) 

messages. 

Default = 6 


5000.0.0 Initialize/Terminate ZPI/O Environment: Internal Routines – SIISIL 41


Argument 

Name 


Argument 

Name 

Data 

Type 

LUNWAR I Logical unit number for output warning 

messages. 

Default = 6 


LUNERO I Logical unit number for output error messages. 

Default = 6 


LUNBUG I Logical unit number for output ZPI/O input and 

output debug messages. 

Default = 6 


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 

Data 

Type 

Description 

and Default 

Description 

and Default 


–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 5000.0.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. 



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 5000.0.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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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 5000.0.0


Argument 

Name 


Argument 

Name 

Data 

Type 

MFDNUM I Number of master file to contain the member data 

file. 


LOGDIC I Logical unit number for the format file. 

Default = 61, if DICFLG = .FALSE. 

62, if DICFLG = .TRUE. 


LOGDAT I Logical unit number for the input formatted data 

file. 

Default = 62 


Data 

Type 

Description 

and Default 

Description 

and Default 


–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 

5000.0.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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

NAMGRD C*24 Name of the input grid file. 

MFDGRD I Number of the master file containing the input 

grid file. 


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 5000.0.0



Argument 

Name 

Data 

Type 

Description 

and Default 

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). 

5000.0.0 Transfer, Convert, or List Information: Internal Routines – S2GRST 47


Argument 

Name 

Data 

Type 

Description 

and Default 



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 5000.0.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. 



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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 


MFDODA I Number of the master file to contain the output 

data file. 


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) 

5000.0.0 Transfer, Convert, or List Information: Internal Routines – S4CDTR 49


Argument 

Name 

Data 

Type 

Description 

and Default 

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 5000.0.0


Argument 

Name 

Data 

Type 

Description 

and Default 

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 Alber’s 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 


0 = Currently not used 

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 Alber’s 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 



Argument 

Name 

Data 

Type 

Description 

and Default 

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: 


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. 



Argument 

Name 

Data 

Type 

Description 

and Default 

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). 




Argument 

Name 

Data 

Type 

Description 

and Default 


–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 



Name Description 

Table 1: Checklist for Projection Arguments vs. Projection Type 

Arguments 

Alber’s Equal Area 

American Polyconic 

Azimuthal Gnomonic 

Azimuthal Orthographic 

Azimuthal Stereographic 

Bipolar Oblique Conic Conformal 

Projection Type 

Cassini-Soldner 

Double Parallel Lambert 

General Transverse Mercator 

5000.0.0 Transfer, Convert, or List Information: Internal Routines – S4CDTR 55 

Modified Polyconic 

New Zealand Map Grid 

Oblique Transverse Mercator 

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 

BOTPAR Least Standard Parallel Y N N N N N N Y N N N N Y 1 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 O 4 N 

IRADTY Radius Calculation Method N N N N N N N N N N N N N N N Y 

REFLAT Reference Latitude Y 1 Y Y Y Y N Y Y Y Y 1 N Y Y N N N 

REFLON Reference Longitude Y 2 Y Y Y Y N Y Y Y Y 2 N Y Y Y O 3 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 Y 2 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 

O = argument optional. If not 

specified, default value is used 

3 Hemisphere defines false northing for UTM 

4 One or the other is required 

* User defined 

Single Parallel Lambert 

Standard Mercator 

Universal Transverse Mercator 

Van Der Grinten I



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. 



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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 


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 5000.0.0



Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

5000.0.0 Transfer, Convert, or List Information: Internal Routines – SICTST 57


Argument 

Name 

Data 

Type 

Description 

and Default 






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 5000.0.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. 



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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

5000.0.0 Transfer, Convert, or List Information: Internal Routines – SIFDST 59


Argument 

Name 


Argument 

Name 

Data 

Type 

WINMAX R Maximum allowed value. Values greater than 

this bound are not used in the computation of the 

statistics. Required only if ALLWIN = 

WINDOW. 

Data 

Type 

Description 

and Default 

Description 

and Default 

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 5000.0.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.”) 



Format CALL SIFLOT ( 

1 NAMDAT , NAMDIC , NAMGRP , NAMFIL , GRPCHR , 

2 CMTCHR , HSTCHR , DICFLG , HDRFLG , MFDNUM , 

3 IHSFIL , LOGDIC , LOGDAT , ISTAT ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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 

5000.0.0 Transfer, Convert, or List Information: Internal Routines – SIFLOT 61


Argument 

Name 


Argument 

Name 

Data 

Type 

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. 


IHSFIL I History display for the member file: 



LOGDIC I Logical unit number for the format file 

Default = 63, if DICFLG = .TRUE. 


LOGDAT I Logical unit number for the output data file. 

Default = 64 


Data 

Type 

Description 

and Default 

Description 

and Default 



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 5000.0.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. 



Format CALL SIGLST ( 

1 NAMGRI , GRDFMT , MFDGRD , IHSGRD , LOGRPT , 

2 IRPTYP , NROWMN , NROWMX , NCOLMN, NCOLMX , 

3 LBRWCL , NUMCTR , NUMPOS , CTRINT , CTRMIN , 

4 ISTAT ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 


IHSGRD I History display for input file: 



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


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 


Default = Number of rows 

5000.0.0 Transfer, Convert, or List Information: Internal Routines – SIGLST 63


Argument 

Name 

Data 

Type 

Description 

and Default 

NCOLMN I Minimum column at which to begin printing (left 


Default = 1 

NCOLMX I Maximum column at which to end printing (right 


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. 


NUMPOS I Number of print positions across the top of plot. 

Needed only if contour plot requested. 

Default = NCOLMX – NCOLMN + 1 


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 5000.0.0



Argument 

Name 

Data 

Type 

Description 

and Default 


–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 5000.0.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) 



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 ) 


Z 8D 1074 = 9 chars = 3 words = 3A4 

Z-MAP #1 = 8 chars = 2 words = 2A4 

ZPIO LISTING = 12 chars = 3 words = 3A4 

Argument 

Name 

Data 

Type 

Description 

and Default 

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. 


IHISDA I History display for the input data file: 



5000.0.0 Transfer, Convert, or List Information: Internal Routines 66


Argument 

Name 

Data 

Type 

Description 

and Default 

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


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 5000.0.0



Argument 

Name 

Data 

Type 

Description 

and Default 


–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. 

5000.0.0 Transfer, Convert, or List Information: Internal Routines 68


Introduction 


Draw and Plot Features 

Use the Draw and Plot Features subroutines for these tasks: 

draw lines from an array or member file 

display and plot a picture 

This section describes the following internal routines for drawing and 

plotting features: 

S2ALIN (page 70) 

S2DSPT (page 72) 

S3ZLIN (page 74) 

5000.0.0 Draw and Plot Features: Internal Routines – Contents 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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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 – Contents 5000.0.0


Argument 

Name 

Data 

Type 

Description 

and Default 

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). 


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. 


Argument Data Description 

Name Type and Default 



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. 




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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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 



Argument 

Name 


Argument 

Name 

Data 

Type 

IDUMMY I Reserved for future use. 

NUMLGB I Number of graphics feature codes in LGBTYP. 

Needed only if ILGBMD is 1 or 2. 


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. 

Data 

Type 

Description 

and Default 

Description 

and Default 



1 = Error, performing hardcopy processing 




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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

NAMZIM C*24 Name of the input data file containing the 

vertices. 

MFDNZM I Number of the master file containing the input 

data file. 


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 



Argument 

Name 

Data 

Type 

Description 

and Default 

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 

0–255= 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 



or cm). 






Argument 

Name 


Argument 

Name 

Data 

Type 

BWIDTH R Width of bold lines, in plotter units (in or cm). 

SYMSIZ R Symbol size, in plotter units (in or cm). 

Data 

Type 

Description 

and Default 

Description 

and Default 



1 = Error, problem drawing lines 

76 Draw and Plot Features 5000.0.0


Introduction 


Graphics Utilities 

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 



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 

5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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.0–360.0 

Data 

Type 

Description 

and Default 



1 = Error, number of markers is zero 

2 = Error, graphics feature is not open 

78 Graphics Utilities: Internal Routines – S2GMRK 5000.0.0



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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 1–14 = $HT 88 NAMZGF 

Col. 15–80 = 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. 


Recommend: 10 

LUNZGF I Number of logical unit on which to open the 

graphics file. 


Recommend: 27 

Data 

Type 

Description 

and Default 



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 

5000.0.0 Graphics Utilities: Internal Routines – S2ZGIN 79



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 


Format CALL S2ZGOT ( 

1 NAMZGF , NAMFLT , NAMPIC , SELECT , NUMPIC , 

3 LEVRPT , LUNZGF , LUNFLT , ISTAT ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 


Recommend: 27 

LUNFLT I Number of logical unit on which to open the 

neutral file. 


Recommend: 99 

80 Graphics Utilities: Internal Routines – S2ZGOT 5000.0.0



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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

LENARY I Length of output arrays. 

Data 

Type 

Description 

and Default 

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 

5000.0.0 Graphics Utilities: Internal Routines – S3GELM 81


Argument 

Name 

Data 

Type 

Description 

and Default 

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 5000.0.0


Argument 

Name 

Data 

Type 

Description 

and Default 

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 


5000.0.0 Graphics Utilities: Internal Routines – S3GELM 83


Argument 

Name 

Data 

Type 

Description 

and Default 

HACDIR R Direction of hachures: 



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 5000.0.0



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 ) 

5000.0.0 Graphics Utilities: Internal Routines – S3IPIC 85



Argument 

Name 

Data 

Type 

Description 

and Default 

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 

Argument 

Name 

Data 

Type 

Description 

and Default 

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 5000.0.0


Argument 

Name 

Data 

Type 

Description 

and Default 

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.) 



Argument 

Name 

Data 

Type 

Description 

and Default 




Conformal 






















Mercator 

2 = Degrees and General Transverse Mercator 


4 = Degrees and Conformal Lambert with one 


5 = Degrees and Conformal Lambert with two 











13 = Degrees and Oblique Transverse 

Mercator 




Conformal 




Argument 

Name 

Data 

Type 

Description 

and Default 

ISPCOD * I Reference spheroid: 




4 = Bessel 1841 

5 = Airy 1858 

6 = Clarke 1858 

7 = Clarke 1866 

8 = Clarke 1880 



11 = Hough 1956 


13 = Kaula 1961 

14 = IUGG 1967 (Australian National 1967/ 



16 = WGS-72 1972 

17 = IUGG 1975 

18 = Helmert 


20 = WGS-84 (GRS-80) 



2 = Meters 

3 = Feet 

4 = Yards 

5 = Inches 










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. 



Argument 

Name 

Data 

Type 

Description 

and Default 

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). 

(VXMAX–VXMIN)/XSCMAP. 

YLONG R The y direction AOI length, in plotter units (in or 

cm). 

(VYMAX–VYMIN)/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. 





Argument 

Name 

Data 

Type 

Description 

and Default 

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. 




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 5000.0.0



Argument 

Name 

Data 

Type 

Description 

and Default 


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. 

5000.0.0 Graphics Utilities: Internal Routines – S3NPIC 93


Argument 

Name 


grad. 


grads. 


grads. 

IHEM * I Hemisphere. Required if IPJCOD = 1: 

1 = Northern 

2 = Southern 

IUTMCD 

* 

Data 

Type 

Description 

and Default 

I UTM zone number. (See “Appendix G. Mapping 

and Cartographic Projections” in the Z-MAP Plus 

Reference Manual.) 



Argument 

Name 

Data 

Type 

Description 

and Default 




Conformal 






















Mercator 











Orthotomic Polyconic) 






Mercator 




Conformal 




Argument 

Name 

Data 

Type 

Description 

and Default 





4 = Bessel 1841 

5 = Airy 1858 

6 = Clarke 1858 

7 = Clarke 1866 

8 = Clarke 1880 



11 = Hough 1956 


13 = Kaula 1961 




16 = WGS-72 1972 

17 = IUGG 1975 

18 = Helmert 


20 = WGS-84 (GRS-80) 



2 = Meters 

3 = Feet 

4 = Yards 

5 = Inches 










4 = Gaussian 







Argument 

Name 


(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 

* 

Data 

Type 

Description 

and Default 

R Projected coordinates units factor. Needed only if 

IUNCOD = 1. 





Argument 

Name 




Argument 

Name 

Data 

Type 

Data 

Type 

Description 

and Default 

Description 

and Default 


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 

Arguments 











5000.0.0 Graphics Utilities: Internal Routines – S3NPIC 99 























Key: 

Y = argument required 



specified, default value is used 

1 


2 


3 

Hemisphere defines false northing for UTM 

4 

One or the other is required 





Van Der Grinten I


YLNVEW 

YLONG 

Cutline 

* 

(0.0,0.0) 

XOFFST 

(VXMIN,VYMIN) 

FREEY 

Scaled Area 

(“User” units) 

YOFFST 

XLONG 

XLNVEW 

No graphics may appear outside “Unscaled” Area 

Display Area for a Picture 

(VXMAX,VYMAX) 

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 

(XLNVEW,YLNVEW) 

FREEX 

Unscaled Area 

(“Plotter” units) 

In General 

TOP/BOTTOM Refers to longitude or eastings 

LEFT/RIGHT SIDES Refers to latitude or northings 




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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 


Data 

Type 

Description 

and Default 





1 = Latitude/Longitude border 


IABSSC I Absolute scale. A value is returned if IFPRJ = 2; 

otherwise, it is set to zero. 


grad. 

5000.0.0 Graphics Utilities: Internal Routines – S3OPIC 101


Argument 

Name 

Data 

Type 

Description 

and Default 


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 



102 Graphics Utilities: Internal Routines – S3OPIC 5000.0.0


Argument 

Name 




Conformal 





















IPJCOD * 

(cont.) 

Data 

Type 

Description 

and Default 

I Cartographic projection code (cont.): 


Mercator 

















Mercator 




Conformal 




Argument 

Name 

Data 

Type 

Description 

and Default 





4 = Bessel 1841 

5 = Airy 1858 

6 = Clarke 1858 

7 = Clarke 1866 

8 = Clarke 1880 



11 = Hough 1956 


13 = Kaula 1961 




16 = WGS-72 1972 

17 = IUGG 1975 

18 = Helmert 


20 = WGS-84 (GRS-80) 


1 = User-supplied 

2 = Meters 

3 = Feet 

4 = Yards 

5 = Inches 










4 = Gaussian 







Argument 

Name 

Data 

Type 

Description 

and Default 


(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. 






Argument 

Name 

Data 

Type 

Description 

and Default 



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. 





Arguments 











5000.0.0 Graphics Utilities: Internal Routines – S3OPIC 107 























Key 




specified, default value is used. 

1 


2 


3 


4 






Van Der Grinten I


YLNVEW 

YLONG 

Cutline 

* 

(0.0,0.0) 

XOFFST 

(VXMIN,VYMIN) 

FREEY 

Scaled Area 


YOFFST 

XLONG 

XLNVEW 



(VXMAX,VYMAX) 












y is YLNVEW 






FREEX 

Unscaled Area 


In General 






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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

NAMPIC C*80 Name of the picture. 

Data 

Type 

Description 

and Default 

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. 

5000.0.0 Graphics Utilities: Internal Routines – S4PCIN 109


Argument 

Name 


1 = Latitude/longitude 

2 = Rectilinear 




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

calculated, otherwise it is set to zero. 

IUTMCD 

* 

Data 

Type 

Description 

and Default 




110 Graphics Utilities: Internal Routines – S4PCIN 5000.0.0


Argument 

Name 

IPJCOD * I Cartographic projection: 



Conformal 






















Mercator 














IPJCOD * 

(cont.) 

Data 

Type 

Description 

and Default 

I Cartographic projection (cont.): 




Mercator 




Conformal 




Argument 

Name 

Data 

Type 

Description 

and Default 





4 = Bessel 1841 

5 = Airy 1858 

6 = Clarke 1858 

7 = Clarke 1866 

8 = Clarke 1880 



11 = Hough 1956 


13 = Kaula 1961 




16 = WGS-72 1972 

17 = IUGG 19 

18 = Helmert 


20 = WGS-84 (GRS-80) 



2 = Meters 

3 = Feet 

4 = Yards 

5 = Inches 






grad. 


grads. 


grads. 


a grad. 


grads. 



Argument 

Name 

Data 

Type 

Description 

and Default 


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 




Argument 

Name 



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 


BOTPAR 

* 

R Standard parallel (least). 

TOPPAR * R Standard parallel (greatest). 


SFLAT * R Reference latitude scale factor. 


SFLON * R Reference longitude scale factor. 

FNORTH 

* 



UNTFAC 

* 

Data 

Type 

Description 

and Default 

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. 



Argument 

Name 

Data 

Type 

Description 

and Default 

SCALE * R Scale factor at origin for Oblique Transverse 

Mercator. 



1 = Error, picture not found 

2 = Error, problem obtaining picture 

information 





Arguments 











116 Graphics Utilities: Internal Routines – S4PCIN 5000.0.0 























Key 





1 


2 


3 


4 






Van Der Grinten I



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 ) 



Argument 

Name 

Data 

Type 

Description 

and Default 



1 = Error, problem closing the currently open 

picture 

5000.0.0 Graphics Utilities: Internal Routines – SIEPIC 117



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 5000.0.0



SIEZIG 

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

This subroutine should be called after all graphics operations have 

been completed. 



Format CALL SIEZIG 



5000.0.0 Graphics Utilities: Internal Routines – SIEZIG 119



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 ) 



Argument 

Name 

Data 

Type 

Description 

and Default 

ICOLOR I Color index for drawing lines, from the color 

table currently defined. 


Argument 

Name 

Data 

Type 

Description 

and Default 



1 = Error, invalid line color index 

120 Graphics Utilities: Internal Routines – SIGLCL 5000.0.0



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 


Format CALL SIGLIN ( NUMPTS , XCORS , YCORS , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

Data 

Type 

Description 

and Default 



1 = Error, number of points is zero 


5000.0.0 Graphics Utilities: Internal Routines – SIGLIN 121



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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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: 



Data 

Type 

Description 

and Default 



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 5000.0.0



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. 






Format CALL SIGLTY ( LTYP , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

LTYP I Type of line: 

1 = Plain 

2 = Dashed 

3 = Hachured 

Data 

Type 

Description 

and Default 



1 = Error, invalid line type 

5000.0.0 Graphics Utilities: Internal Routines – SIGLTY 123



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. 






Format CALL SIGLWD ( WIDTH , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

WIDTH R Line width. This is a scalar by which the standard 

line width is multiplied to get a new line width. 


Data 

Type 

Description 

and Default 



1 = Error, invalid line width 

124 Graphics Utilities: Internal Routines – SIGLWD 5000.0.0



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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

ICOLOR I Color index for drawing markers, from the color 



Data 

Type 

Description 

and Default 



1 = Error, invalid marker color index 

5000.0.0 Graphics Utilities: Internal Routines – SIGMCL 125



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. 






Format CALL SIGMHT ( HEIGHT , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

HEIGHT R Height for markers, in plotter units (in or cm). 

Data 

Type 

Description 

and Default 



1 = Error, marker height is less than or equal 

to zero 

126 Graphics Utilities: Internal Routines – SIGMHT 5000.0.0



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. 






Format CALL SIGMTY( MARKER , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

MARKER I Symbol code for type of marker. (See “Appendix 

C. Symbols, Fonts, and Line Patterns ” in the 


Data 

Type 

Description 

and Default 



1 = Error, invalid marker type 

5000.0.0 Graphics Utilities: Internal Routines – SIGMTY 127



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. 






Format CALL SIGPCL ( ICOLOR , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

ICOLOR I Color index for filling polygons, from the color 



Data 

Type 

Description 

and Default 



1 = Error, invalid polygon color index 

128 Graphics Utilities: Internal Routines – SIGPCL 5000.0.0



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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

KLNCLR I Color index for drawing lines, from the color 


Default = 1 (black on plotter, white on screen) 


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. 



KMKTYP I Symbol code for marker type. (See “Appendix C. 

Symbols, Fonts, and Line Patterns ” in the 


Default = 1 (little cross) 


5000.0.0 Graphics Utilities: Internal Routines – SIGPDF 129


Argument 

Name 

Data 

Type 

Description 

and Default 

KTXTCL I Color index for drawing text, from the color table 

currently defined. 



KTXTFO I Type of text font. (See “Appendix C. Symbols, 



1 = Plain 



4 = Italics 

5 = Duplex 

Default = 1 

KIXTJU I Text justification: 



3 = Centered 

Default = 1 

KPOLCL I Color index for drawing colorfilled polygons, 

from the color table currently defined. 



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 5000.0.0


Argument 

Name 


Argument 

Name 

Data 

Type 

ROTEXT R Text rotation angle, in degrees. 

Default = 0.0 


DSHLEN R Length of the solid part of the dash, in plotter 



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). 





Default = 1.0 

Data 

Type 

Description 

and Default 

Description 

and Default 



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 

5000.0.0 Graphics Utilities: Internal Routines – SIGPDF 131



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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

Data 

Type 

Description 

and Default 



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 5000.0.0



SIGSCL 

Function Close current graphics feature 






Format CALL SIGSCL ( ISTAT ) 



Argument 

Name 

Data 

Type 

Description 

and Default 



1 = Error, closing graphic feature 

2 = Error, no graphics feature is currently 

open 

5000.0.0 Graphics Utilities: Internal Routines – SIGSCL 133



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. 






Format CALL SIGSCS ( ISCALE , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

ISCALE I Type of coordinate system: 

1 = Engineering units 

2 = Plotter units (in or cm) 

Data 

Type 

Description 

and Default 



1 = Error, invalid scale type 

134 Graphics Utilities: Internal Routines – SIGSCS 5000.0.0



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. 






Format CALL SIGSDL ( ISEGTY , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

ISEGTY I Graphics feature number for the graphics feature 

to delete. (See “Appendix A. Graphics Feature 

Codes” in the Z-MAP Plus Reference Manual.) 

Data 

Type 

Description 

and Default 


–1 = Warning, graphics feature has been closed 


1 = Error, invalid graphics feature number 

2 = Error, unsuccessful delete 

3 = Error, problem closing graphics feature 

5000.0.0 Graphics Utilities: Internal Routines – SIGSDL 135



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. 






Format CALL SIGSOP ( ISEGTY , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

ISEGTY I Graphics feature number for the graphics feature 

to open. (See “Appendix A. Graphics Feature 


Data 

Type 

Description 

and Default 



1 = Error, invalid graphics feature number 

2 = Error, problem opening graphics feature 

136 Graphics Utilities: Internal Routines – SIGSOP 5000.0.0



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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

ICOLOR I Color index for drawing text, from the color table 

currently defined. 


Data 

Type 

Description 

and Default 



1 = Error, invalid text color index 

5000.0.0 Graphics Utilities: Internal Routines – SIGTCL 137



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. 






Format CALL SIGTFO ( IFONT , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

IFONT I Type of text font. (See “Appendix C. Symbols, 



Data 

Type 

1 = Plain 



4 = Italics 

5 = Duplex 

Description 

and Default 



1 = Error, invalid font type 

138 Graphics Utilities: Internal Routines – SIGTFO 5000.0.0



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. 






Format CALL SIGTHT ( HEIGHT , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

HEIGHT R Height of text, in plotter units (in or cm). 

Data 

Type 

Description 

and Default 



1 = Error, text height is less than or equal to 

zero 

5000.0.0 Graphics Utilities: Internal Routines – SIGTHT 139



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. 






Format CALL SIGTJU ( JUSTIF , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

JUSTIF I Justification method: 



3 = Center 

Data 

Type 

Description 

and Default 



1 = Error, invalid justification type 

140 Graphics Utilities: Internal Routines – SIGTJU 5000.0.0



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. 






Format CALL SIGTRO ( ANGLE , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

ANGLE R Angle at which to draw text, in degrees from 

horizontal. 


Data 

Type 

Description 

and Default 



1 = Error, invalid text rotation angle 

5000.0.0 Graphics Utilities: Internal Routines – SIGTRO 141



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. 






Format CALL SIGTXT( 

1 TEXT , NCHAR , XCORS , YCORS , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

TEXT C*80 Text string of length NCHAR. 

NCHAR I Number of characters in text string. 


XCORS R The x coordinate of text. 

YCORS R The y coordinate of text. 

Data 

Type 

Description 

and Default 




142 Graphics Utilities: Internal Routines – SIGTXT 5000.0.0




Arguments 











5000.0.0 Graphics Utilities: Internal Routines – SIGTXT 143 























Key 



O = argument optional.If not 


1 


2 


3 


4 






Van Der Grinten I


YLNVEW 

YLONG 

Cutline 

* 

(0.0,0.0) 

XOFFST 

(VXMIN,VYMIN) 

FREEY 

Scaled Area 


YOFFST 

XLONG 

XLNVEW 



(VXMAX,VYMAX) 












y is YLNVEW 






FREEX 

Unscaled Area 


In General 



144 Graphics Utilities: Internal Routines – SIGTXT 5000.0.0



SIIZGF 

Function Open a graphics file 



Format CALL SIIZGF ( 

1 ZGFNAM , HISNEW , IFNEW , HISOLD , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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 

Data 

Type 

Description 

and Default 

HISOLD C*80 Header of an old graphics file. 



1 = Error, opening graphics file 

2 = Error, invalid graphics file type 

5000.0.0 Graphics Utilities: Internal Routines – SIIZGF 145



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 5000.0.0



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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

5000.0.0 Graphics Utilities: Internal Routines – SIOVLY 147



Argument 

Name 

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. 

Argument 

Name 

Data 

Type 

Data 

Type 

Description 

and Default 

Description 

and Default 



1 = Error, copying graphics information 

2 = Error, problem positioning index map 

148 Graphics Utilities: Internal Routines – SIOVLY 5000.0.0



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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

5000.0.0 Graphics Utilities: Internal Routines – SIPCAS 149


Argument 

Name 


Argument 

Name 

Data 

Type 


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. 

Data 

Type 

Description 

and Default 

Description 

and Default 


–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 5000.0.0


YLNVEW 

YLONG 

YLNVEW 

YLONG 

Cutline 

(0.0,0.0) 

Cutline 

* 

(0.0,0.0) 

Border 

XOFFST 

(VXMIN,VYMIN) 

Border 

XOFFST 

(VXMIN,VYMIN) 

* 

(XLL,YLL) 

FREEY 

YOFFST 

XLONG 

XLNVEW 

“Copy To” Space 

FREEY 

Scaled Area 


YOFFST 

XLONG 

XLNVEW 

“Copy From” Space 

(VXMAX,VYMAX) 

(VXMAX,VYMAX) 

“Copy To” Space and “Copy From” Space 


FREEX 


FREEX 

Unscaled Area 


5000.0.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 5000.0.0



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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

5000.0.0 Graphics Utilities: Internal Routines – SIPCCP 153



Argument 

Name 

Data 

Type 

Description 

and Default 



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 5000.0.0



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: 

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 ) 


( XBOUND(1) YBOUND(1) ) = (X1, Y1) 




Argument 

Name 

Data 

Type 

Description 

and Default 

PICFRM C*80 Name of input Copy From picture. 

PICTO C*80 Name of output Copy To picture. 

(X1,Y2) (X2,Y2) 

(X1,Y1) (X2,Y1) 

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 

5000.0.0 Graphics Utilities: Internal Routines – SIPCDF 155


Argument 

Name 


Argument 

Name 

Data 

Type 

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. 

Data 

Type 

Description 

and Default 

Description 

and Default 

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 5000.0.0


“Copy To” 

Space 

“Copy From” 

Space 

YLNVEW 

YLONG 

YLNVEW 

YLONG 

Cutline 

(0.0,0.0) 

Cutline 

* 

(0.0,0.0) 

Border 

XOFFST 

XOFFST 

Argument 

Name 

Data 

Type 

Description 

and Default 

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 


(VXMIN,VYMIN) 

Border 

(VXMIN,VYMIN) 

* 

(XLLIN,YLLIN) 

FREEY 

YOFFST 

XLONG 

XLNVEW 

FREEY 

Scaled Area 


YOFFST 

XLONG 

XLNVEW 

(XLRIN,YLRIN) 

“Copy To” Space and “Copy From” Space 

(VXMAX,VYMAX) 

FREEX 

(VXMAX,VYMAX) 



FREEX 

Unscaled Area 


5000.0.0 Graphics Utilities: Internal Routines – SIPCDF 157













y is YLNVEW 





In General 



158 Graphics Utilities: Internal Routines – SIPCDF 5000.0.0



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 


Format CALL SIPCDL ( NAMPIC , ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

NAMPIC C*80 Name of the picture to be marked for deletion. 

Data 

Type 

Description 

and Default 



1 = Error, problem reading picture header 

2 = Error, problem writing picture header 


5000.0.0 Graphics Utilities: Internal Routines – SIPCDL 159



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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

Data 

Type 

Description 

and Default 

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 5000.0.0



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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

NAMOLD C*80 Name of the picture to be renamed. 

NAMNEW C*80 New name for the picture. 

Data 

Type 

Description 

and Default 



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 5000.0.0



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 ) 



Argument 

Name 

Data 

Type 

Description 

and Default 

PICNAM C*80 Name of the picture. 

Argument 

Name 

Data 

Type 

Description 

and Default 




5000.0.0 Graphics Utilities: Internal Routines 162



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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

ZGFOLD C*80 Name of the graphics file to be compressed. 

ZGFNEW C*80 Name of the new compressed graphics file. 

Data 

Type 

Description 

and Default 



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? 

Argument 

Name 

Data 

Type 

Description 

and Default 


–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 




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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

NDXCLR I Color index. 


Data 

Type 

Description 

and Default 

REDPCT R Fraction red. 


GRNPCT R Fraction green. 


BLUPCT R Fraction blue. 




1 = Error, no color table on picture 

2 = Error, invalid color index 




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 






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 ) 




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 


Format CALL SOGLGB ( QPCEND , LGBCOD , CTRLEV , ISTAT ) 



Argument 

Name 

Data 

Type 

Description 

and Default 

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 


CTRLEV R Contour level for contour graphics features. 



1 = Error, no graphics feature on this picture 



Introduction 


File Utilities 

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 



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. 

5000.0.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 5000.0.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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

5000.0.0 File Utilities: Internal Routines – S2FLST 171


Argument 

Name 


Argument 

Name 

Data 

Type 

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). 

Data 

Type 

Description 

and Default 


Description 

and Default 


–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 5000.0.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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 


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. 

5000.0.0 File Utilities: Internal Routines – S2IZIM 173



Argument 

Name 

Data 

Type 

Description 

and Default 

ISTAT I Default = Status flag: 

–1 = Warning, runtime directory is being reset 

to 20 


1–4 = 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 5000.0.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 

NUMGEN = 1 

Child (current) 

Parent Parent 

NUMGEN = 2 Ancestor Ancestor Ancestor Ancestor 

NUMGEN = 3 


this routine. 

Format CALL S2LHIS ( 

1 NAMFIL , MFDFIL , IHSFIL , NUMGEN , LOGRPT , 

2 IPRINT , ISTAT ) 

5000.0.0 File Utilities: Internal Routines – S2LHIS 175 

Ancestor 

Ancestor 

Ancestor 

Ancestor 

Ancestor 

Ancestor 

Ancestor 

Ancestor



Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

NAMFIL C*24 Name of the file whose history is to be printed. 

MFDFIL I Number of the master file containing the input 

file. 


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. 


LOGRPT I Logical unit on which to print the report. 

Default = 6 


IPRINT I Type of history to print: 

0 = Print standard history parameters 

1 = Print standard and proposed history 

parameters 

Data 

Type 

Description 

and Default 


–1 = Warning, there are no history records. 




2 = Error, duplicate files. Specify master file 

number. 



176 File Utilities: Internal Routines – S2LHIS 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

Data 

Type 

Description 

and Default 


–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 

5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

NAMDAT C*24 Name of the input data file. 

MFDDAT I Number of the master file that contains the input 

data file. 


IHSDAT I History display for input file: 


Data 

Type 

Description 

and Default 

NAMFLD C*20 Array of the file’s 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 5000.0.0


Argument 

Name 

Data 

Type 

Description 

and Default 

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 Alber’s Equal Area (equivalent) 

with two standard parallels 

–9 = Grads and Modified Rectangular Orthotomic 

Polyconic 












1 = Degrees and Universal Transverse Mercator 

2 = Degrees & General Transverse Mercator 











10= Degrees and Alber’s Equal Area equivalent 

with two standard parallels 



13 = Degrees and Oblique Mercator 


15= Degrees and Cassini-Soldner 


Conformal 


5000.0.0 File Utilities: Internal Routines – S5DAFU 179


Argument 

Name 





4 = Bessel 1841 

5 = Airy 1858 

6 = Clarke 1858 

7 = Clarke 1866 

8 = Clarke 1880 



11 = Hough 1956 


13 = Kaula 1961 




16 = WGS-72 1972 

17 = IUGG 1975 

18 = Helmert 


20 = WGS-84 (GRS-80) 

IUNCOD 

* 

IUTMCD 

* 

Data 

Type 

Description 

and Default 

I Units for projected coordinates: 


2 = Meters 

3 = Feet 

4 = Yards 

5 = Inches 








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. 



Argument 

Name 

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 

* 

TOPPAR 

* 

REFLAT 

* 

R Standard parallel closest to the equator (least), in 

degrees. 

R Standard parallel closest to pole (greatest), in 

degrees. 

R Reference latitude. 

SFLAT * R Scale factor for the reference latitude. 

REFLON 

* 

R Reference longitude. 

SFLON * R Scale factor for the reference longitude. 

FNORTH 

* 



UNTFAC 

* 

Data 

Type 

Description 

and Default 

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. 



5000.0.0 File Utilities: Internal Routines – S5DAFU 181


Argument 

Name 

Data 

Type 

Description 

and Default 

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 

Arguments 












5000.0.0 File Utilities: Internal Routines – S5DAFU 183 























Key: 





1 


2 


3 Hemisphere defines false northing for UTM 

4 One or the other is required 





Van Der Grinten I



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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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 5000.0.0


Argument 

Name 


Argument 

Name 

Data 

Type 


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. 

Data 

Type 

Description 

and Default 

Description 

and Default 

VECTOR R Array (of length 20) containing the following 

information: 

1–5 = Field name 

6 = Field type 

7 = Field output format type 

8 = Field width 

9 = Number of decimals for the field 

10 = Index of the field’s first word 

11 = Number of words for the field 


13 = Null value 

14 = Minimum allowed z value 

15 = Maximum allowed z value 

16–19 = Currently not used 

20 = Sort field index 

5000.0.0 File Utilities: Internal Routines – SIDFFD 185


Argument 

Name 

Data 

Type 

Description 

and Default 


–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 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

Data 

Type 

Description 

and Default 

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 

5000.0.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 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

LOGFIL I Logical file code for the member file to be 

closed. 


Data 

Type 

Description 

and Default 



1 = Error, problem closing file 

5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

LOGFIL I Logical file code to access the file. 


NUMFLD I Number of field descriptor to be read. 

Data 

Type 

Description 

and Default 

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 5000.0.0


Argument 

Name 

Data 

Type 

Description 

and Default 

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 

5000.0.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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

FLDNAM C*20 Field name. 

IFMT C*1 Output conversion type. 

Range Options: A,I,F,E or G 



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 5000.0.0


Argument 

Name 


Argument 

Name 

Data 

Type 

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

0 = None 


FMIN R Minimum allowed field value. 

FMAX R Maximum allowed field value. 

Data 

Type 

Description 

and Default 

Description 

and Default 



1 = Error, writing direct access file 

5000.0.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 ) 



Argument 

Name 

Data 

Type 

Description 

and Default 



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. 

Argument 

Name 

Data 

Type 

Description 

and Default 

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 5000.0.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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

LOGFIL I Logical file code to access file. 


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. 

5000.0.0 File Utilities: Internal Routines – SIFWRT 195



Argument 

Name 

Data 

Type 

Description 

and Default 

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 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 


LUNDRC I Runtime directory physical unit number. This 

variable is currently reset to 20. 

Note: This variable is reserved for future use. 

Data 

Type 

Description 

and Default 


–1 = Warning, runtime directory is reset to 20 


1–4 = Sequential number of the master file that 

could not be opened 

5 = Error, opening scratch file 

6 = Error, opening runtime directory 

5000.0.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: 


this routine. This capability is not available for nondynamic allocating 

systems. 

Format CALL SIMFAT ( NAMMFD , ISTAT ) 


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 = 

Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

NAMMFD C*80 Disk name of the master file to be attached. 

Data 

Type 

Description 

and Default 






2 = Error, 5 master files attached already 

3 = Error, master file not found 

198 File Utilities: Internal Routines – SIMFAT 5000.0.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 ) 



Argument 

Name 

Data 

Type 

Description 

and Default 

LUNCFM I Logical unit of master file to copy files from. 


LUNCTO I Logical unit of master file to copy files into. 


Argument 

Name 

Data 

Type 

Description 

and Default 

NUMCPY I Number of member files copied. 



1 = Error, problem compressing master file 

5000.0.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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 


200 File Utilities: Internal Routines – SIMFCR 5000.0.0



Argument 

Name 

Data 

Type 

Description 

and Default 




2 = Error, master file FORTRAN unit is zero 

3 = Error, opening FORTRAN file 

4 = Error, writing to file 

5000.0.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: 


this routine. 

This capability is not available for nondynamic allocating systems. 

Format CALL SIMFDT ( NAMMFD , ISTAT ) 


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 = 

Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 

Data 

Type 

Description 

and Default 





1 = Error, problem reinitializing ZIMS 

2 = Error, no match for the disk master file 

202 File Utilities: Internal Routines – SIMFDT 5000.0.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 ) 



Argument 

Name 

Data 

Type 

Description 

and Default 

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 


5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

NAMMFD C*80 Disk name of the master file. 

NAMINT C*24 New internal name of the master file. 

Data 

Type 

Description 

and Default 



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 5000.0.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 21–24 of NAMRET contain the 

version number. 


this routine. 

Format CALL SINOPN ( 

1 NAMZIM , INWTYP , MFDNZM , NAMRET , LOGFIL , 

2 ISTAT ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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 


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. 


Data 

Type 

Description 

and Default 

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. 



–1 = Warning, duplicate files. A version 

number has been added. 




2 = Error, invalid version number. 


5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

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. 


IHISZM I History display for input file: 



Data 

Type 

Description 

and Default 

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. 






2 = Error, duplicate files 



206 File Utilities: Internal Routines – SIOOPN 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



Data 

Type 

Description 

and Default 

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. 

5000.0.0 File Utilities: Internal Routines – SIPRRC 207


Argument 

Name 

Data 

Type 

Description 

and Default 

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 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



Data 

Type 

Description 

and Default 

NFLDS I Number of data fields on the file. 




0 = None 





ZNON R Null data value for the file. 




5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



Data 

Type 

Description 

and Default 

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 5000.0.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 ) 


Argument 

Name 

Data 

Type 

Description 

and Default 


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 




5000.0.0 File Utilities: Internal Routines – SIPRWC 211



Argument 

Name 



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. 

Argument 

Name 

Data 

Type 

Data 

Type 

Description 

and Default 

Description 

and Default 



212 File Utilities: Internal Routines – SIPRWC 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 


Range Options: 1- 5 

NFLDS I Number of data fields in the file. 




0 = None 






Data 

Type 

Description 

and Default 



5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



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. 

Data 

Type 

Description 

and Default 



214 File Utilities: Internal Routines – SIPRWG 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



IWORD I Word number to position file to. 

Data 

Type 

Description 

and Default 


–1 = Warning, end of file 


1 = Error, invalid member file unit 

2 = Error, invalid word position 


5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



IWORD I Word location at which to start reading. 

NWORDS I Number of words to be read. 

Data 

Type 

Description 

and Default 

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 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



NWORDS I Number of words to be read. 

Data 

Type 

Description 

and Default 

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. 

5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



IHREC I Number of the history record to be retrieved or 

zero for all history records. 

Data 

Type 

Description 

and Default 

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 5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 

INFHIS C*80 Array (of length NORECS) containing the 

history information. 

NORECS I Number of records to be written. 


LOGFIL I Logical file code to access member file. 


Data 

Type 

Description 

and Default 

NTHREC I Total number of history records on the member 

file. 



1 = Error, record number invalid 

2 = Error, writing the history information 

5000.0.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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



IWORD I Word number at which to position the file. 

Data 

Type 

Description 

and Default 



1 = Error, invalid member file unit 



220 File Utilities: Internal Routines – SIWRPO 5000.0.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 ) 



Argument 

Name 

Data 

Type 

Description 

and Default 



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. 

Argument 

Name 

Data 

Type 

Description 

and Default 



1 = Error, invalid member file number 



4 = Error, writing file 

5000.0.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 file’s 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 ) 


Argument 

Name 


Argument 

Name 

Data 

Type 

Description 

and Default 



NWORDS I Number of words to be written. 

ARRAY R Array (of length NWORDS) containing the data 

to be written. 

Data 

Type 

Description 

and Default 



1 = Error, invalid member logical file 


3 = Error, writing file 

222 File Utilities 5000.0.0


Introduction 

ZIGS File Structure 

Picture Components 

Appendix A. 

ZIGS Overview 

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. 

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. 

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 5000.0.0


Headers 

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 


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. 

5000.0.0 Appendix A. ZIGS Overview 224


ZGF Header 

Header – Picture 1 

Header – Picture z 

LGB 1 

LGB 2 

LGB K 

Primitive 1 

Primitive 2 

Primitive n 

Primitive 1 

Primitive 2 

Primitive m 

ZIGS File Structure 



ZIGS Programmer’s Guide 

Input Graphics to a Picture 

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. 

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 

C 

C 

C 

C 




CALL SIIZIG 

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. 

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. 

ZGFNAM = ’/disk/directory/my.zgf’ 






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 ’ 


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 



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, 








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: 


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: 


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 

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 




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 



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. 




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 


CALL SIEZIG 

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 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. 





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. 





Introduction 

Appendix B. 

ZIMS Overview 

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 file’s 

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 file’s 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 5000.0.0


ZIMS File Structure 

Master File 

MFD Header 

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. 

Header – File 1 

Parameter Record (Grid) 

Header – File 2 

Grid Column 1 Data 

Grid Column 2 Data 

Grid Column n Data 

Parameter Record (Data) 

Field Descriptor 1 

Field Descriptor 2 

Field Descriptor n 

ZIMS File Structure 

Data Record 1 

Data Record n 

5000.0.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 


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 

5–6 Double Minimum x value XMIN 

7–8 Double Maximum x value XMAX 

9–10 Double Minimum y value YMIN 

11–12 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 

21–32 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 


Word Type Content AKA 

1 Integer Number of fields on data record (also the number 

of field descriptor records) 

2 Integer Number of words per data record (equal to the sum 

of the “number of words” entries from all the field 

descriptors) 

NFLDS 

NWRDS 

3 Integer Number of data records in file NRECS 

4 Integer Distribution type code (See the list below.) 

5–6 Double Minimum x coordinate XMIN 

7–8 Double Maximum x coordinate XMAX 

9–10 Double Minimum y coordinate YMIN 

11–12 Double Maximum y coordinate YMAX 

13–17 

19–20 

18 Real Null data value for file ZNON 

21 Real Marker or separator value for contour, seismic 

section, or cross-section files 

22 

25–29 

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 

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. 

Word Type Content 

Field Descriptor Record 


1–5 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 

16–19 

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). 

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: 

record 1 

record 2 

record 3 

• 

• 

• 

record (maximum) 

X-field Y-field Z1-field Name-field • • • 

The data records follow the final field descriptor record. 



ZIMS Programmer’s Guide 

Creating a Member File 

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. 

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. 

Warning – Call SICOMM or SIISIL First 


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 file’s 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. 

Warning — Call SICOMM or SIISIL First 


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. 





Appendix C. 

Logical Unit Assignment 

The Logical Unit Assignment Table contains a list of the logical 

FORTRAN units used throughout ZPI/O. 

5000.0.0 Appendix C. Logical Unit Assignment 248 

C

249 Appendix C. Logical Unit Assignment 5000.0.0 

Description Logical 

Unit 

Logical Unit Assignment Table 

Symbolic 

Name 

Common 

Block 

Defining 

Routine 

Data 

Format 

Maximum 

Size 

Record 

Format 

Volumetrics output 9 LFRMAT (none) ZVOLUM Character 200 rec. Fixed 

Blocked 

Import Task formatted data input/output—may be 

unused. 

ZIMS Runtime File Directory (RTD), contains a list 

of all datasets accessed in this run. 

ZIMS Master Files (MFD), contain all data listed in 

RTD above. 

ZIMS Scratch MFD used for run-temporary 

datasets. 

ZIMS Scratch file used for MFD file deletion and 

clean up. 

ZIGS Graphics File (ZGF), contains new or old 

plots. 

ZIGS auxiliary Graphics File used for copy and 

cleanup. 

10 LUNFMT (none) ZXFGRD 

ZXFDAT 

ZXFSUP 

Character User 

Specified 

Record 

Length 

File 

Allocation 

132 byte Permanent 

(if used) 

Permanent 

(if used) 

20 LUNDIR DIRECT ZILDDR Binary 250 rec. Direct 32 word Run 

Temporary 

21 

22 

23 

24 

(none) FBUFCM 

FBUFCM 

FBUFCM 

FBUFCM 

ZILDDR Binary 500 rec. Direct 

Access 

25 (none) FBUFCM ZILDDR Binary 500 rec. Direct 


26 

26 

27 

27 

LUNNEW 

LUNSCR 

LZGF 

LUNQ 

(none) 

(none) 

ZGFCOM 

(none) 

ZIGRCL 

ZIMFDD 

ZGFINF 

ZMDSPL 

Binary 500 rec. Direct 




28 LUNAUX (none) ZGCOPY Binary 500 rec. Direct 


ZIGS color table 39 LUNIT (none) ZDINIT Character 500 rec. Fixed/ 

Blocked 

ZIGS Workstation file 40 LUN (none) ZGBGWD Character 400 rec. Fixed/ 

Blocked 

Alternate color table (reading) 41 LUNIT (none) ZDCRCT Character 500 rec. Fixed/ 

Blocked 

Alternate color table (writing) 42 LUNIT (none) ZDCWCT Character 500 rec. Fixed/ 

Blocked 

Filter scratch file 76 

76 

LUNSCR 

LUNSCR 

(none) ZFBIHR 

SOBIHR 



512 word Permanent 

512 word Run 

Temporary 

512 word Run 

Temporary 


or Run 

Temporary 


(if used) 




(if used) 


(if used) 

4096 word Run 

Temporary 

Z-MAP Plus I/O Access Library Landmark Graphics

5000.0.0 Appendix C. Logical Unit Assignment 250 

Description Logical 

Unit 

Lithology symbol table 37 LUNSYM SCLOGU STISYM Binary 512 rec. Direct 


Log Curve Default File 51 LDFLG 

LUNLOG 

Lithology and Cross-Section Default File 52 LDEFS 

LUNDEF 

Definition File 53 LNLST 

LGNLST 

Lithology Data File 55 LLITH 

LUNLIT 

Tops Data File 56 LTOPS 

LUNTOP 

Log Curve Data File 57 LLOGS 

LUNLOG 

Analysis Data File 58 LANLY 

LUNANL 

(none) 

SCLOGU 

(none) 

SCLOGU 

(none) 

SCLDMX 

(none) 

SCLDMX 

(none) 

SCLDMX 

(none) 

SCLDMX 

(none) 

SCLDMX 

SLOPEN 

SGCOMN 

SLOPEN 

SGCOMN 

SLOPEN 

SLCOMM 

SLOPEN 

SLCOMM 

SLOPEN 

.SLCOMM 

SLOPEN 

SLCOMM 

SLOPEN 

SLCOMM 

Character Fixed/ 

Blocked 


Blocked 


.Blocked 


Blocked 


.Blocked 


Blocked 


Blocked 

Core Data File 59 LUNCOR SCLDMX SLCOMM Character Fixed/ 

Blocked 

Well Survey Data File 60 LWSV 

LUNWSR 

Logical Unit Assignment Table 

Symbolic 

Name 

Common 

Block 

(none) 

SCLDMX 

Defining 

Routine 

SLOPEN 

SLCOMM 

Data 

Format 

Maximum 

Size 

Record 

Format 


Blocked 

Record 

Length 

File 

Allocation 











Landmark Graphics Z-MAP Plus I/O Access Library

251 Appendix C. Logical Unit Assignment 5000.0.0 

Z-MAP Plus I/O Access Library Landmark Graphics


Symbols 

.assemble picture 

“copy to” space vs. “copy from” space 151 

A 

A-MAP Plus I/O 

example program 14–24 

argument name 

variable vs. constant 29 

assemble picture 149–152 

“copy to” space vs. “copy from” space 157 

compute four corners for 155–158 

attach master file 177, 198 

C 

close 

current graphics feature 133 

files 30 

graphics file 118 

last picture opened 117 

master files 188 

member file 189 

ZIMS files 40 

color table 224 

compress 


master file 199 

compute 

control point file statistics 56–58 

four corners of one picture relative to another picture 

for assembly/overlay 155–158 

grid file statistics 46–48 

statistics for field 59–60 

convert from x,y to latitude/longitude 49–53 

copy all or part of a picture to another picture 153–154 

create new master file 200 

create new member file 32, 242–244 

D 

debugging option 

using 29 

Index 

defaults 

set field descriptors 184–186 

set for lines, markers, text, and polygons 129–131 

define coordinate system 134 

delete 

graphics feature from picture file 135 

mark picture for 159 

member file from master file 170 

detach one or all master files 202 

display area of a picture 100, 108, 144 

display/plot hardcopy type picture 72–73 

draw 

connected line segments 121 

lines using a member file 74 

lines using array inputs 70 

markers 78 

shaded or colorfilled polygon 132 

text 142 

5000.0.0 Index 252 

E 

example program 

to list members of a graphics file 10–13 

to list members of a master file 8–9 

G 

graphics feature 

defined 223 

graphic primitives 224 

set attributes 229–230 

graphics file 

close 133 

compress 163 

header 224 

open 145 

transfer picture from neutral file to 79 

transfer picture to neutral file from 80–164 


list members of, example program 10–13 

grids 

reading and writing 34


H 

header 224 

I 

IDBUG 

using 29 

index maps 147–148 

initialize 38 

all input arguments 29 

ZPI/O environment 38 

with output file control 41–42 

ZPI/O output graphics environment 167 

Zycor Information Management System (ZIMS) and 

attach master files 173–174, 197 

Zycor Interactive Graphics Environment (ZIGS) 146 

internal routines 

draw/plot features 69 

file utilities 169 

graphic utilities 77 

initialize/terminate ZPI/O environment 36 

transfer, convert, list information 43 

internal routines, defined 29 

ISTAT 

using 30 

L 

LGB 

header 224 

set attributes 229–230 

LGB, defined 223 

line 

draw connected segments 121 

draw using a member file 74 

draw using array inputs 70 

set color 120 

set dash and hachure mark parameters 122 

set defaults 129–131 

set type 123 

set width 124 

list 

attached master files 203 

data file 66–68 

file history and its ancestry 175–176 

grid as grid or contours 63–65 

member files 171–172 

example program 8–9 

list member files 

example graphics program 10–13 

logical file code 237 

logical unit assignment 248–250 

253 Index 5000.0.0 

M 

mark picture for deletion 159 

marker 

draw 78 

set color 125 


set height 126 

set type 127 

master file 

attach 177, 198 

compress 199 

create new 200 

rename internal name of 204 

master files 

close 188 

detach one or all 202 

list attached 203 

list members of, example program 8–9 

specifying the number of 31 

member file 

create 32 

create new 242–244 

open new 205 

open old 206 

output filename 33 

position for sequential read 215 

position for sequential write 220 

read from 32 

read from at random location 216 

read from sequentially 31, 217 

read history information from 218 

write history records to 219 

write to at random location 221 

write to sequentially 31, 222 

O 

obtain 

color representation for color index 165 

general, projection and graphics feature information 

for picture 109–115 

graphics from a picture 233–234 

next graphics feature for picture 168 

next valid graphics element from picture 81–84 

parameter, projection, and field information about data 

file 178–183 

picture name by picture index 160 

open 

files 30 


new graphics feature 136 

new member file 32, 205 

new or old picture 85–144 

new picture 92–100


old member file 206 

old picture 101–108 

old picture read only 162 

overlay maps or generate index maps 147–148 

overlay picture 149–152 

“copy to” space vs. “copy from” space 151, 157 

compute four corners for 155–158 

P 

picture 

“copy to” space vs. “copy from” space 151, 157 

copy all or part to another picture 153–154 

header 224 

mark for deletion 159 

obtain graphics element from 81–84 

obtain graphics from 233–234 

obtain information 109–115 

obtain name by picture index 160 

obtain next graphics feature for 168 

open new 92–100 

open new or old 85–144 

open old 101–108 

open old, read only 162 

place graphics 226–232 

projection arguments vs. projection type 107 

rename 161 

transfer from graphics file to neutral file 80–164 

transfer from neutral file to graphics file 79 

polygon 

draw shaded or colorfilled 132 


position member file 

for sequential read 215 

for sequential write 220 

R 

read 

data parameter record 209 

field descriptor 190–191 

from member file 32, 245–246 

from member file at random location 216 

from member file sequentially 31, 217 

general data or contour parameter record 207–208 

grid 34, 247 

grid parameter record 210 

history information from member file 218 

position member file for sequential 215 

record from member file 194 

rename 

internal name of master file 204 

picture 161 

reset debug print flag 37 

retrieve information 

about member file from run time directory 187 

5000.0.0 Index 254 

S 

set 

dash line and hachure mark parameters 122 

default field descriptors 184–186 

defaults for lines, markers, text, and polygons 

129–131 

line color 120 

line type 123 

line width 124 

marker color 125 

marker height 126 

marker type 127 

polygon fill color 128 

text color 137 

text font 138 

text height 139 

text justification 140 

text rotation 141 

status flag, using 30 

subroutine descriptions, presentation of information 

25–28 

T 

terminate 


ZPI/O output graphics environment 166 

Zycor Interactive Graphics Environment (ZIGS) 119 

text 

draw 142 

set color 137 


set font 138 

set height 139 

set justification 140 

set rotation 141 

transfer 

contents (pictures) of neutral file to graphics file 79 

information from external file into member of master 

file 44–45 

information from member of master file to external file 

61–62 

pictures from graphics file to neutral file 80–164 

V 

variable argument name 29


W 

write 

data parameter record 213 

field descriptor 192–193 

from member file sequentially 31 

general data or contour parameter record 211–212 

grid 34, 247 

grid parameter record 214 

history records to member file 219 

position member file for sequential 220 

record to member file 195–196 

to member file at random location 221 

to member file sequentially 222 

Z 

Z-MAP Interactive Graphics System 

file structure 223–225 

file structure example 225 

programmer’s guide 226–234 

Z-MAP Plus I/O 

program structure 6 


Zycor Information Management System 

field descriptor record 240 

file structure 236–240 

file structure example 236 

parameter record for data 240 

parameter record for grids 238 

programmer’s guide 242–247 

Zycor Information Management System (ZIMS) 

initialize and attach master files 173–174, 197 

Zycor Interactive Graphics Environment (ZIGS) 

initialize 146 

255 Index 5000.0.0

Z-MAP Plus I/O Access Library - Landmark Software Manager ...

Create successful ePaper yourself

Delete template?

Save as template?