T4.7: Uses APIs for Common Operations

Knowledge Review - InterSystems ObjectScript Specialist

1. %Stream para E/S de archivos

Puntos Clave

  • %Stream.FileCharacter: Leer/escribir archivos de texto con soporte de codificación de caracteres
  • %Stream.FileBinary: Leer/escribir archivos binarios (imágenes, PDFs, etc.)
  • Propiedad .Filename: Establezca la ruta del archivo antes de leer o escribir
  • .Write() / .WriteLine(): Escribir contenido al stream
  • .Read(len): Leer hasta len caracteres/bytes del stream
  • .ReadLine(): Leer una línea de texto (para streams de caracteres)
  • .Rewind(): Restablecer la posición al inicio del stream
  • .MoveToEnd(): Posicionar al final del stream (para agregar contenido)
  • .AtEnd: Propiedad que es verdadera cuando no hay más datos para leer
  • .Size: Propiedad que contiene el tamaño total del stream

Notas Detalladas

Descripción general

Las clases %Stream proporcionan el mecanismo estándar de E/S de archivos de ObjectScript. A diferencia de los lenguajes tradicionales que usan manejadores de archivo, InterSystems IRIS usa objetos stream que encapsulan el archivo, su posición y su codificación. Los streams también se usan extensamente en servicios web, BLOBs/CLOBs de SQL y producciones de interoperabilidad.

Escritura de un archivo de texto

 SET stream = ##class(%Stream.FileCharacter).%New()
 SET stream.Filename = "/tmp/output.txt"

 // Write content
 DO stream.WriteLine("Line 1: Hello World")
 DO stream.WriteLine("Line 2: ObjectScript")
 DO stream.Write("No newline at end")

 // Save the stream to disk
 SET status = stream.%Save()
 IF $$$ISERR(status) {
     WRITE "Error saving: ", $SYSTEM.Status.GetErrorText(status), !
 } ELSE {
     WRITE "File written successfully", !
 }

Lectura de un archivo de texto

 SET stream = ##class(%Stream.FileCharacter).%New()
 SET stream.Filename = "/tmp/output.txt"

 // Check if file exists via Size
 IF stream.Size = 0 {
     WRITE "File is empty or does not exist", !
     QUIT
 }

 // Read line by line
 WHILE 'stream.AtEnd {
     SET line = stream.ReadLine()
     WRITE line, !
 }

Lectura de un número fijo de caracteres

 SET stream = ##class(%Stream.FileCharacter).%New()
 SET stream.Filename = "/tmp/largefile.txt"

 // Read in chunks of 32000 characters
 WHILE 'stream.AtEnd {
     SET chunk = stream.Read(32000)
     // Process chunk...
     SET totalLen = totalLen + $LENGTH(chunk)
 }
 WRITE "Total characters read: ", totalLen, !

Operaciones con archivos binarios

 // Copy a binary file
 SET input = ##class(%Stream.FileBinary).%New()
 SET input.Filename = "/tmp/image.png"

 SET output = ##class(%Stream.FileBinary).%New()
 SET output.Filename = "/tmp/image_copy.png"

 // Copy content
 WHILE 'input.AtEnd {
     SET chunk = input.Read(32000)
     DO output.Write(chunk)
 }
 SET status = output.%Save()

Navegación de streams

 SET stream = ##class(%Stream.FileCharacter).%New()
 SET stream.Filename = "/tmp/data.txt"

 // Read first line
 SET firstLine = stream.ReadLine()
 WRITE "First: ", firstLine, !

 // Rewind to beginning
 DO stream.Rewind()

 // Read everything
 SET all = stream.Read(stream.Size)

 // Move to end for appending
 DO stream.MoveToEnd()
 DO stream.WriteLine("Appended line")
 SET status = stream.%Save()

Copia entre streams

 // CopyFrom copies one stream's content into another
 SET source = ##class(%Stream.FileCharacter).%New()
 SET source.Filename = "/tmp/source.txt"

 SET dest = ##class(%Stream.FileCharacter).%New()
 SET dest.Filename = "/tmp/dest.txt"

 SET status = dest.CopyFrom(source)
 SET status = dest.%Save()

Resumen de propiedades y métodos de streams

 SET stream = ##class(%Stream.FileCharacter).%New()
 SET stream.Filename = "/tmp/test.txt"

 // Properties
 WRITE "Size: ", stream.Size, !           // Total size in characters/bytes
 WRITE "At End: ", stream.AtEnd, !        // 1 if position is at end
 WRITE "Filename: ", stream.Filename, !   // File path

 // Key Methods
 // stream.Read(len)       - Read up to len chars
 // stream.ReadLine()      - Read one line (text streams)
 // stream.Write(data)     - Write data
 // stream.WriteLine(data) - Write data + newline
 // stream.Rewind()        - Go to beginning
 // stream.MoveToEnd()     - Go to end
 // stream.CopyFrom(src)   - Copy from another stream
 // stream.Clear()         - Remove all content
 // stream.%Save()         - Persist changes to disk

Referencias de Documentación

2. %Net para HTTP, FTP y correo electrónico

Puntos Clave

  • %Net.HttpRequest: Enviar solicitudes HTTP GET, POST, PUT, DELETE
  • %Net.HttpResponse: Objeto de respuesta con StatusCode, Data (stream), encabezados
  • %Net.FtpSession: Conectar a servidores FTP, subir/descargar archivos
  • %Net.SMTP: Enviar mensajes de correo electrónico vía SMTP
  • %Net.MailMessage: Componer mensajes de correo electrónico con adjuntos
  • SSL/TLS: Configurar vía propiedad SSLConfiguration para conexiones HTTPS
  • Timeout: Establecer tiempos de espera para evitar bloqueos en servidores que no responden

Notas Detalladas

Descripción general

El paquete %Net proporciona clases para protocolos de red comunes. %Net.HttpRequest maneja la comunicación HTTP (APIs REST, servicios web), %Net.FtpSession gestiona transferencias de archivos FTP, y %Net.SMTP envía correo electrónico. Estas clases son esenciales para integrar InterSystems IRIS con sistemas externos.

Solicitud HTTP GET

 SET request = ##class(%Net.HttpRequest).%New()
 SET request.Server = "api.example.com"
 SET request.Port = 443
 SET request.Https = 1
 SET request.SSLConfiguration = "MySSLConfig"
 SET request.Timeout = 30

 // Send GET request
 SET status = request.Get("/api/users/1")
 IF $$$ISERR(status) {
     WRITE "Request failed: ", $SYSTEM.Status.GetErrorText(status), !
     QUIT
 }

 // Read response
 SET response = request.HttpResponse
 WRITE "Status: ", response.StatusCode, !
 WRITE "Content-Type: ", response.GetHeader("Content-Type"), !

 // Read response body
 SET body = ""
 WHILE 'response.Data.AtEnd {
     SET body = body _ response.Data.Read(32000)
 }
 WRITE "Body: ", body, !

Solicitud HTTP POST con JSON

 SET request = ##class(%Net.HttpRequest).%New()
 SET request.Server = "api.example.com"
 SET request.ContentType = "application/json"

 // Build JSON body using %DynamicObject
 SET json = {}
 SET json.name = "Alice"
 SET json.age = 30
 SET json.city = "New York"

 // Write JSON to request body
 DO request.EntityBody.Write(json.%ToJSON())

 // Send POST
 SET status = request.Post("/api/users")
 IF $$$ISOK(status) {
     WRITE "Created! Status: ", request.HttpResponse.StatusCode, !
 }

HTTP con encabezados personalizados

 SET request = ##class(%Net.HttpRequest).%New()
 SET request.Server = "api.example.com"

 // Set custom headers
 DO request.SetHeader("Authorization", "Bearer " _ token)
 DO request.SetHeader("Accept", "application/json")
 DO request.SetHeader("X-Custom-Header", "value")

 SET status = request.Get("/api/protected-resource")

Manejo de respuesta HTTP

 // Check status codes
 SET response = request.HttpResponse
 IF response.StatusCode = 200 {
     // Parse JSON response
     SET jsonStr = response.Data.Read(response.Data.Size)
     SET obj = {}.%FromJSON(jsonStr)
     WRITE "Name: ", obj.name, !
 } ELSEIF response.StatusCode = 404 {
     WRITE "Not found", !
 } ELSEIF response.StatusCode >= 500 {
     WRITE "Server error: ", response.StatusCode, !
 }

Operaciones FTP

 SET ftp = ##class(%Net.FtpSession).%New()
 SET ftp.Server = "ftp.example.com"
 SET ftp.Username = "user"
 SET ftp.Password = "pass"

 // Connect
 SET status = ftp.Connect()
 IF $$$ISERR(status) {
     WRITE "FTP connect failed", !
     QUIT
 }

 // Change directory
 DO ftp.SetDirectory("/uploads")

 // Upload a file
 SET stream = ##class(%Stream.FileBinary).%New()
 SET stream.Filename = "/tmp/upload.txt"
 SET status = ftp.Store("remote_file.txt", stream)

 // Download a file
 SET download = ##class(%Stream.FileBinary).%New()
 SET download.Filename = "/tmp/downloaded.txt"
 SET status = ftp.Retrieve("remote_file.txt", .download)
 DO download.%Save()

 // List directory
 SET status = ftp.List(.list)

 // Disconnect
 DO ftp.Logout()

Envío de correo electrónico vía SMTP

 // Create the email message
 SET msg = ##class(%Net.MailMessage).%New()
 SET msg.From = "sender@example.com"
 DO msg.To.Insert("recipient@example.com")
 DO msg.Cc.Insert("cc@example.com")
 SET msg.Subject = "Test Email from IRIS"
 SET msg.IsSent = 0
 SET msg.IsHTML = 1

 // HTML body
 DO msg.TextData.Write("<h1>Hello!</h1>")
 DO msg.TextData.Write("<p>This email was sent from InterSystems IRIS.</p>")

 // Add attachment
 SET status = msg.AttachFile("/tmp", "report.pdf")

 // Configure and send via SMTP
 SET smtp = ##class(%Net.SMTP).%New()
 SET smtp.smtpserver = "smtp.example.com"
 SET smtp.port = 587
 SET smtp.timezone = "US/Eastern"

 // Authentication
 SET auth = ##class(%Net.Authenticator).%New()
 SET auth.UserName = "user@example.com"
 SET auth.Password = "password"
 SET smtp.authenticator = auth

 // Send
 SET status = smtp.Send(msg)
 IF $$$ISOK(status) {
     WRITE "Email sent successfully", !
 } ELSE {
     WRITE "Failed: ", $SYSTEM.Status.GetErrorText(status), !
 }

Correo electrónico de texto plano

 SET msg = ##class(%Net.MailMessage).%New()
 SET msg.From = "noreply@example.com"
 DO msg.To.Insert("admin@example.com")
 SET msg.Subject = "Alert: System Notification"
 SET msg.IsHTML = 0

 // Plain text body
 DO msg.TextData.Write("This is a plain text alert.")
 DO msg.TextData.Write($CHAR(13, 10))    // CRLF
 DO msg.TextData.Write("Please check the system.")

 SET smtp = ##class(%Net.SMTP).%New()
 SET smtp.smtpserver = "smtp.example.com"
 SET status = smtp.Send(msg)

Referencias de Documentación

Resumen de Preparación para el Examen

Conceptos críticos a dominar:

  1. %Stream.FileCharacter vs %Stream.FileBinary: Streams de caracteres para texto, binarios para todo lo demás
  2. Patrón de lectura de streams: WHILE 'stream.AtEnd { SET data = stream.Read(len) }
  3. Escritura de streams: .Write() para contenido crudo, .WriteLine() agrega nueva línea, .%Save() persiste en disco
  4. Navegación de streams: .Rewind() para ir al inicio, .MoveToEnd() para agregar, .AtEnd para verificar si hay más datos
  5. Flujo de %Net.HttpRequest: Crear -> Establecer Server/Port -> Establecer Headers -> Get/Post -> Leer HttpResponse
  6. El cuerpo de respuesta es un stream: request.HttpResponse.Data es un %Stream -- léalo como cualquier stream
  7. Envío SMTP: Crear %Net.MailMessage -> Configurar %Net.SMTP -> smtp.Send(msg)
  8. Flujo FTP: Crear %Net.FtpSession -> Connect -> Store/Retrieve -> Logout
  9. Configuración SSL: Establecer propiedad SSLConfiguration para HTTPS; requiere configuración SSL preconfigurada en IRIS
  10. Manejo de errores: Siempre verifique los valores de retorno %Status de operaciones de red

Escenarios comunes de examen:

  • Escribir código para leer un archivo de texto línea por línea usando %Stream.FileCharacter
  • Enviar una solicitud HTTP GET y procesar la respuesta JSON
  • Elegir entre FileCharacter y FileBinary para un tipo de archivo dado
  • Configurar una solicitud HTTP POST con cuerpo JSON y encabezados personalizados
  • Enviar un correo electrónico con adjunto usando %Net.SMTP y %Net.MailMessage
  • Leer el cuerpo de una respuesta HTTP desde la propiedad stream Data
  • Manejar operaciones de streams: Rewind, Read, AtEnd, MoveToEnd
  • Configurar transferencia de archivos FTP con %Net.FtpSession

Recomendaciones de práctica:

  • Escribir un archivo de texto, luego leerlo línea por línea usando %Stream.FileCharacter
  • Copiar un archivo binario usando %Stream.FileBinary con lecturas por bloques
  • Enviar solicitudes HTTP GET a una API pública y analizar respuestas JSON
  • Enviar solicitudes HTTP POST con cuerpos JSON
  • Configurar una prueba SMTP simple para enviar correo electrónico (use un servidor SMTP de prueba)
  • Practicar navegación de streams: escribir, rebobinar, leer, mover al final, agregar
  • Usar CopyFrom para copiar contenido entre streams
  • Experimentar con códigos de estado y encabezados de respuesta HTTP

Report an Issue