Rocket U2 Clients and APIs

InterCall Developer’s Guide

Version 4.1.1

September 2015 UCC-411–INTR-DG-01 Notices

Edition Publication date: September 2015 Book number: UCC-411–INTR-DG-01 Product version: Version 4.1.1

Copyright © Rocket Software, Inc. or its affiliates 1988-2015. All Rights Reserved.

Trademarks Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go to: www.rocketsoftware.com/about/legal. All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names of their respective owners.

Examples This information might contain examples of data and reports. The examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

License agreement This software and the associated documentation are proprietary and confidential to Rocket Software, Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance with the terms of such license.

Note: This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product.

2 Corporate information

Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks, and compliance; database servers and tools; business information and analytics; and application development, integration, and modernization. Website: www.rocketsoftware.com Rocket Global Headquarters 77 4th Avenue, Suite 100 Waltham, MA 02451-1468 USA To contact Rocket Software by telephone for any reason, including obtaining pre-sales information and technical support, use one of the following telephone numbers.

Country Toll-free telephone number United States 1-855-577-4323 1-800-823-405 Belgium 0800-266-65 1-855-577-4323 800-720-1170 0800-180-0882 08-05-08-05-62 Italy 800-878-295 0800-170-5464 Netherlands 0-800-022-2961 0800-003210 South Africa 0-800-980-818 0800-520-0439

Contacting Technical Support The Rocket Customer Portal is the primary method of obtaining support. If you have current support and maintenance agreements with Rocket Software, you can access the Rocket Customer Portal and report a problem, download an update, or find answers to in the U2 Knowledgebase. To log in to the Rocket Customer Portal or to request a Rocket Customer Portal account, go to www.rocketsoftware.com/support. In addition to using the Rocket Customer Portal to obtain support, you can send an email to [email protected] or use one of the following telephone numbers.

Country Telephone number North America +1 800 729 3553 United Kingdom/France +44 (0) 800 773 771 or +44 (0) 20 8867 3691 Europe/Africa +44 (0) 20 8867 3692 Australia +1 800 707 703 or +61 (0) 29412 5450 New Zealand +0800 505 515

3 Contents

Notices...... 2 Corporate information...... 3 Chapter 1: Introduction...... 7 About InterCall...... 7 Minimum system requirements...... 7 InterCall installation...... 7 On Windows platforms...... 8 On UNIX systems...... 8 How InterCall works...... 8 Copying the software...... 8 UniVerse NLS in client programs...... 9 NLS configurable parameters...... 9 Character mapping...... 9 Locale conversion...... 9 System delimiters and the null value...... 10 The sample program...... 10 Chapter 2: Programming with InterCall...... 11 Server sessions...... 11 Using the Microsoft security token...... 11 Argument passing conventions...... 11 The ICSTRING type...... 12 Calling functions from C programs...... 12 Calling functions from Visual Basic programs...... 12 Size of output buffers...... 13 Using the @TTY variable...... 13 Chapter 3: InterCall functions...... 15 Function summary...... 15 Error codes...... 16 ic_alpha...... 17 ic_calloc...... 17 ic_cleardata...... 18 ic_clearfile...... 18 ic_clearselect...... 19 ic_close...... 19 ic_closeseq...... 20 ic_data...... 20 ic_date...... 21 ic_delete...... 22 ic_execute...... 22 ic_executecontinue...... 23 ic_extract...... 24 ic_fileinfo...... 25 ic_filelock...... 27 ic_fileunlock...... 27 ic_fmt...... 28 ic_formlist...... 29 ic_free...... 30 ic_get_ipv...... 30 ic_getlist...... 30 ic_get_locale...... 31

4 Contents ic_get_map...... 32 ic_get_mark_value...... 33 ic_getvalue...... 33 ic_get_sessionipv...... 35 ic_iconv...... 35 ic_indices...... 36 Finding the name of secondary indexes...... 37 Returning information about a secondary index...... 37 ic_inputreply...... 37 ic_insert...... 38 ic_itype...... 39 ic_locate...... 40 ic_lock...... 41 ic_lower...... 42 ic_malloc...... 42 ic_oconv...... 43 ic_open...... 44 ic_openseq...... 45 ic_opensession...... 46 ic_quit...... 48 ic_quitall...... 48 ic_raise...... 48 ic_read...... 49 ic_readblk...... 51 ic_readlist...... 52 ic_readnext...... 52 ic_readseq...... 53 ic_readv...... 54 ic_recordlock...... 56 ic_recordlocked...... 57 ic_release...... 59 ic_remove...... 59 ic_replace...... 61 ic_seek...... 61 ic_select...... 62 ic_selectindex...... 63 ic_session_info...... 64 ic_set_comms_timeout...... 65 ic_set_ipv...... 66 ic_set_locale...... 66 ic_set_map (UniVerse only)...... 67 ic_setsession...... 68 ic_setvalue...... 68 ic_strdel...... 69 ic_subcall...... 70 ic_time...... 71 ic_timedate...... 72 ic_trans...... 73 ic_unlock...... 74 ic_unidata_session...... 74 ic_universe_session...... 76 ic_weofseq...... 77 ic_write...... 77 ic_writeblk...... 79 ic_writeseq...... 79 ic_writev...... 80

5 Contents

Appendix A: InterCall functions by use...... 82 Accessing a server...... 82 Reading and modifying records...... 82 Reading and modifying sequential files...... 82 Accessing and modifying strings...... 83 Accessing and modifying select lists...... 83 Managing database files...... 83 Using UniVerse NLS (UniVerse only)...... 84 Using system utilities...... 84 Appendix B: Error codes...... 85 Database error codes...... 85

6 Chapter 1: Introduction

About InterCall

InterCall is an API (application programming interface) that enables a UNIX or Windows client to access data on UniVerse and UniData servers. With InterCall, your applications can: ▪ Connect to one or more servers ▪ Access files and records ▪ Execute database commands and BASIC programs UniObjects for Java supports the IPv6 protocol, while maintaining IPv4 compatibility. On Windows, you can write applications for client programs using any development tool that accesses DLLs, for example, Visual Basic, C, or Visual C/C++. On UNIX, you can use any tool that accesses static libraries, typically a C compiler. Minimum system requirements

To run InterCall applications, you need the following: ▪ On a UNIX server: ▪ UniVerse Release 8.3.3.1G or later, or UniData Release 5.1 or later ▪ TCP/IP ▪ UniRPC daemon (unirpcd) running ▪ On a Windows server: ▫ UniVerse Release 9.3.1 or later, or UniData Release 5.1 or later ▫ TCP/IP, if connected to a UNIX client ▫ TCP/IP or LAN Manager, if connected to a Windows client ▫ UniRPC service (unirpc) running ▪ On a UNIX client: ▫ TCP/IP ▪ On a Windows client: ▪ TCP/IP, if connected to a UNIX server ▪ TCP/IP or LAN Manager, if connected to a Windows server ▪ Required InterCall files copied from the development system To develop InterCall applications, C-language development tools must be available on the system you are using for development. InterCall installation

The installation of InterCall is different on Windows platforms and UNIX platfor