CONTENTS Title Page Copyright Page 1 Introduction to SQL Multimedia 1.1 What Is SQL Multimedia? 1.2 Who Uses SQL Multimedia? 1.3 Why Use SQL Multimedia? 1.4 What Programming Language Does SQL Multimedia Support? 1.5 How Does SQL Multimedia Work? 1.6 What Software and Hardware Does SQL Multimedia Require? 1.7 What Are the Definitions for the SQL Multimedia Components? 1.8 Where Can I Go for More Information? 1.8.1 In This Manual 1.8.2 In VMS Online Help 1.8.3 In Related Manuals 2 Guidelines for Using SQL Multimedia 2.1 Using Include Files 2.2 Defining a Multimedia Column 2.3 Passing Arguments 2.4 Inserting an Object 2.5 Fetching an Object 2.6 Fetching Legacy Data 2.7 Transferring Buffered Data 2.8 Processing an Image Object 2.8.1 Compressing and Decompressing Objects 2.8.2 Generating Renditions of Multimedia Objects 2.9 Retrieving Metadata 2.10 Specifying File Attributes 3 Building Application Programs 3.1 Building SQL Multimedia Programs with SQL 3.1.1 Building an Application Program with the SQL Module Language 3.1.2 Building an Application Program with the SQL Precompiled Language 3.2 Building SQL Multimedia Programs with SQL/Services 3.2.1 Building Applications on the VMS Operating System 3.2.2 Building Applications on the MS-DOS Operating System 3.2.2.1 Building MS-DOS Applications 3.2.2.2 Building Microsoft Windows Applications 3.2.3 Building Applications on the ULTRIX for RISC Operating System 3.2.4 Building Applications on the Macintosh Operating System 3.2.4.1 Building MPW Applications 3.2.4.2 Building THINK C Applications 4 Using SQL Multimedia SQL Routines SQLMM$SQL_INSERT SQLMM$SQL_FETCH SQLMM$SQL_FETCH_OBJECT_INFO SQLMM$SQL_FREE_MEMORY SQLMM$SQL_BUF_XFER_COMPLETED 5 Using SQL Multimedia SQL/Services Routines sqlmm_sqls_insert sqlmm_sqls_fetch sqlmm_sqls_fetch_object_info sqlmm_sqls_free_memory sqlmm_sqls_buf_xfer_completed 6 Understanding Arguments 6.1 Common Specifications and Arguments 6.1.1 Memory Object Format 6.1.1.1 Application-Defined Memory Object Format 6.1.1.2 Text Memory Object Format 6.1.1.3 DECimage Frame Memory Object Format 6.1.2 Object Descriptor Data Structure (SQLMM_OBJ_DESC) 6.1.3 src_object_desc 6.1.3.1 Specifying a Memory Source 6.1.3.2 Specifying a DECimage Frame Source 6.1.3.3 Specifying a File Source 6.1.3.4 Specifying a CDA-Compatible Buffered I/O Interface Source 6.1.3.5 Specifying an All-Purpose Buffered I/O Interface Source 6.1.4 dest_object_desc 6.1.4.1 Specifying a Memory Destination 6.1.4.2 Specifying a DECimage Frame Destination 6.1.4.3 Specifying a File Destination 6.1.4.4 Specifying a CDA-Compatible Buffered I/O Interface Destination 6.1.4.5 Specifying an All-Purpose Buffered I/O Interface Destination 6.1.5 object_class and object_format 6.1.6 addr_buffer_put_fn for CDA-Compatible Buffered I/O Interface 6.1.6.1 buffer_put_param 6.1.6.2 buffer_len 6.1.6.3 buffer_addr 6.1.6.4 next_buffer_len 6.1.6.5 next_buffer_addr 6.1.7 addr_buffer_put_fn for All-Purpose Buffered I/O Interface 6.1.7.1 buffer_put_param 6.1.7.2 buffer_len 6.1.7.3 buffer_addr 6.1.8 Inserting Multimedia Data Using the Buffered I/O Interfaces 6.1.9 addr_buffer_get_fn for CDA-Compatible Buffered I/O Interface 6.1.9.1 buffer_get_param 6.1.9.2 buffer_len 6.1.9.3 buffer_addr 6.1.10 addr_buffer_get_fn for All-Purpose Buffered I/O Interface 6.1.10.1 buffer_get_param 6.1.10.2 buffer_len 6.1.10.3 reserve_field 6.1.10.4 buffer_addr 6.1.10.5 return_buffer_len 6.1.11 Fetching Multimedia Data Using the Buffered I/O Interfaces 6.2 SQL Arguments 6.2.1 transaction_context 6.2.2 table_name 6.2.3 object_key_column_names 6.2.4 object_key_values 6.3 SQL/Services Arguments 6.3.1 table_cursor_name 6.3.2 table_name 6.3.3 object_key_column_names 6.3.4 object_key_values 7 Processing Image Objects 7.1 Processing Overview 7.1.1 Advantages to Processing Images 7.1.2 Restrictions on Processing 7.1.3 SQLMM_ITEM_ENTRY Data Structure 7.1.4 Rendition Identification 7.2 Using the SQLMM_ITEM_ENTRY Data Structure During Insert Operations 7.2.1 Rules for Storing the Source Image 7.3 Using the SQLMM_ITEM_ENTRY Data Structure During Fetch Operations 7.3.1 Rules for Fetching Renditions 7.4 Processing Operations 7.4.1 Compressing and Decompressing an Image 7.4.2 Scaling an Image 7.4.3 Dithering an Image 7.4.3.1 Dither Algorithms 7.4.3.2 Dither Thresholds 7.4.3.3 Quantization Levels 7.4.4 Labeling a Rendition 7.4.5 Fetching a Rendition 8 Retrieving Metadata 8.1 Using the Fetch Object Information Routine 8.2 FETCH_OBJECT_INFO Options 8.2.1 General Object Attributes 8.2.2 Image Object Attributes 8.2.3 File Object Attributes 8.2.3.1 VMS File Attributes 8.2.3.2 ULTRIX File Attributes 8.2.3.3 MS-DOS File Attributes 8.2.3.4 Macintosh File Attributes 9 Specifying File Attributes 9.1 About File Attributes 9.2 File Organization Behavior 9.3 Using the SQLMM_ITEM_ENTRY Data Structure 9.4 VMS File System 9.4.1 VMS Environment-Specific File Attributes 9.4.2 VMS Default File Attributes 9.4.3 VMS Item Codes 9.5 ULTRIX File System 9.5.1 ULTRIX Environment-Specific File Attributes 9.5.2 ULTRIX Default File Attributes 9.5.3 ULTRIX Item Code 9.6 MS-DOS File System 9.6.1 MS-DOS Environment-Specific File Attributes 9.6.2 MS-DOS Default File Attributes 9.6.3 MS-DOS Item Codes 9.7 Macintosh File System 9.7.1 Macintosh Environment-Specific File Attributes 9.7.2 Macintosh Default File Attributes 9.7.3 Macintosh Item Codes A SQL Multimedia Error Handling A.1 Returned Values A.2 Online Explanation Files B Using Online Sample Programs B.1 Prerequisites to Running Sample Programs B.2 Building and Running Sample Programs B.2.1 In VMS, ULTRIX, MS-DOS, MS Windows, and MPW Environments B.2.2 In a Macintosh THINK C Environment B.3 Sample Program Locations B.4 Sample Program Descriptions C Hints for Using SQL Multimedia C.1 Designing and Tuning a Multimedia Database C.2 Writing Multimedia Transactions D Remembering Notes and Restrictions D.1 Using the Connect Qualifier When Building Programs D.2 Specifying a Network Transport D.3 Building an ULTRIX for RISC Program Without DECnet D.4 Building an Application on THINK C D.5 Executing the Buffer Transfer Completed Routine D.6 Using SQLMM_K_STREAM as Data Source D.7 Inserting Multiple DDIF Images into a Single Column D.8 Insert Restrictions on Object Source and Format D.9 Fetch Restrictions on Object Destination and Format D.10 Fetch Restriction on MS-DOS and MS Windows D.11 Using the Buffer Put Function D.12 Using the Buffered I/O Interface During an Insert Operation D.13 Using the Buffered I/O Interface During a Fetch Operation D.14 Using the CDA-Compatible Buffered I/O Interface During an Insert Operation D.15 Using the CDA-Compatible Buffered I/O Interface During a Fetch Operation D.16 Specifying Correct File Attributes D.17 Setting Up an Item List D.18 Processing Images While Specifying File Attributes EXAMPLES 4-1 SQLMM$SQL_INSERT Call for Blob Object 4-2 SQLMM$SQL_FETCH Call for Blob Object 5-1 sqlmm_sqls_insert Call for Blob Object 5-2 sqlmm_sqls_fetch Call for Blob Object 6-1 DECdtm Context Structure 6-2 Starting a Distributed Transaction B-1 BLDSAMP_CDA.COM Command File for SAMPCDA.C Program C-1 Using Default Page and Buffer Sizes C-2 Setting Page and Buffer Sizes FIGURES 1-1 SQL Multimedia Product Environment 1-2 Storing an Insurance Form in a DEC Rdb Database 6-1 Data Structure for Object Descriptor (SQLMM_OBJ_DESC) 6-2 Data Structure for Object Key Column Names Argument 6-3 Data Structure for Single Object Key Values List (SQLMM_OKVL) 6-4 Data Structure for Multiple Object Key Values List (SQLMM_OKVL) 7-1 Data Structure for Item Entry (SQLMM_ITEM_ENTRY) 7-2 Data Structure for Processing Operations 8-1 Data Structure for Information Entry (SQLMM_INFO_ENTRY) TABLES 1-1 SQL Multimedia Definitions 2-1 Include Files 2-2 Buffered I/O Interfaces 6-1 Object Location Values 6-2 object_class Argument 6-3 object_format Argument 6-4 Object Class, Identifier, Valid Format, and Data Example 7-1 SQLMM_ITEM_ENTRY Field Descriptions 7-2 Image Compression State Options 7-3 DAS Image Compression Parameters 7-4 Image Compression and Decompression Rules 7-5 Image Scale Options 8-1 Information Entry Data Fields 9-1 VMS Default File Attributes 9-2 VMS File Attribute Item Codes 9-3 ULTRIX Default File Attributes 9-4 ULTRIX File Attribute Item Code 9-5 MS-DOS Default File Attributes 9-6 MS-DOS File Attribute Item Codes 9-7 Macintosh Default File Attributes 9-8 Macintosh File Attribute Item Codes B-1 Sample Programs and Command Files B-2 Sample Programs and Their Functions